<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<!--
Copyright 2008-2016 Conrad Sanderson (http://conradsanderson.id.au)
Copyright 2008-2016 National ICT Australia (NICTA)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<html>
<head>
  <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type">
  <title>Armadillo: API Documentation</title>
  <link rel="icon" href="armadillo_icon.png" type="image/png">
  <style type="text/css">
  <!--
body
  {
  /* font-family: "Trebuchet MS", "Droid Sans", sans-serif; */
  font-family: "Trebuchet MS", sans-serif;
  color: #000000;
  background-color: #FFFFFF;
  /* font-size: 10pt; */
  /* line-height: 120%; */
  height: 110%;
  }

pre
  {
  font-family: "DejaVu Sans Mono", "Liberation Mono", "Andale Mono", "Bitstream Vera Sans Mono", "Luxi Mono", monospace;
  /* font-size: smaller; */
  color: #666666;
  }

a
  {
  text-decoration: none;
  color: #498c05;
  }

a:hover
  {
  text-decoration: underline;
  color: #498c05;
  }

a.menu
  {
  text-decoration: none;
  color: #CCCCCC;
  }

a.menu:hover
  {
  text-decoration: none;
  color: #498c05;
  }

a.latent, a.latent:hover, a.latent:active, a.latent:link, a.latent:visited
  {
  text-decoration: none;
  border-bottom: 0px;
  color: #000000;
  }

table
  {
  /* border: 1px solid #000; */
  /* display: block; */
  border-collapse: collapse;
  }

td.line
  {
  border-left: 2px solid rgb(204, 204, 204);
  }

.footertext
  {
  position: relative;
  bottom: 0px;
  }

hr.greyline
  {
  color: rgb(204, 204, 204);
  /* background-color: rgb(204, 204, 204); */
  }


#nobreak
  {
  white-space: nowrap;
  } 

.noindent
  {
  text-indent:    0px;
  margin-left:    1ex;
  margin-right:   0ex;
  margin-top:     0ex;
  margin-bottom:  0ex;
  padding-left:   1ex;
  padding-right:  0ex;
  padding-top:    0ex;
  padding-bottom: 0ex;
  list-style:     disc;
  }
  -->
  </style>
</head>
<body>


<center>
<table style="text-align: left; width: 80%; margin-left: auto; margin-right: auto;" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td style="vertical-align: top;">


<!-- BEGIN CONTENT -->


<style type="text/css">
<!--
@media all
  {
  .pagebreak { }
  .noprint   { }
  }

@media print
  {
  .pagebreak { page-break-before: always; }
  .noprint   { display: none !important;  }
  }
-->
</style>

<a class="noprint" style="display:scroll; position:fixed; bottom:5px; right:5px;" href="#top"><font size=-1>[top]</font></a>

<a name="top"></a>
<big><b>API Documentation for Armadillo 10.1</b></big>
<br>
<br>
<br>


<b>Preamble</b>
<br>
<br>
<table border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td style="text-align: left; vertical-align: top; width: 45%;">
<ul>
<li>
For converting Matlab/Octave programs,
see the <a href="#syntax">syntax conversion table</a>
</li>
<br>
<li>
First time users: please see the short <a href="#example_prog">example program</a>
</li>
<br>
<li>
If you discover any bugs or regressions, please <a href="http://arma.sourceforge.net/faq.html">report them</a>
</li>
<br>
<li>
History of <a href="#api_additions">API additions</a>
</li>
</ul>
</td>
<td>
&nbsp;
</td>
<td class="line" style="vertical-align: top;">
<br>
</td>
<td style="text-align: left; vertical-align: top; width: 50%;">
<ul>
<li>
Please cite the following papers if you use Armadillo in your research and/or software.
<br>
Citations are useful for the continued development and maintenance of the library.
<br>
<br>
Conrad Sanderson and Ryan Curtin.
<br><i><a href="armadillo_joss_2016.pdf">Armadillo: a template-based C++ library for linear algebra</a></i>.
<br>Journal of Open Source Software, Vol.&nbsp;1, pp.&nbsp;26, 2016.
<br>
<br>
Conrad Sanderson and Ryan Curtin.
<br><i><a href="armadillo_lncs_2018.pdf">A User-Friendly Hybrid Sparse Matrix Class in C++</a></i>.
<br>Lecture Notes in Computer Science (LNCS), Vol.&nbsp;10931, pp.&nbsp;422-430, 2018.
</li>
</ul>
</td>
</tr>
</tbody>
</table>

<br>
<br>

<b>Overview</b>
<ul>
<li><a href="#part_classes">matrix, vector, cube and field classes</a></li>
<li><a href="#part_membfns">member functions &amp; variables</a></li>
<br>
<li><a href="#part_gen">generated vectors&nbsp;/&nbsp;matrices&nbsp;/&nbsp;cubes</a></li>
<li><a href="#part_fns">functions of vectors&nbsp;/&nbsp;matrices&nbsp;/&nbsp;cubes</a></li>
<br>
<li><a href="#part_decompdense">decompositions, factorisations, inverses and equation solvers (dense matrices)</a></li>
<li><a href="#part_decompsparse">decompositions, factorisations, and equation solvers (sparse matrices)</a></li>
<br>
<li><a href="#part_sigproc">signal &amp; image processing</a></li>
<li><a href="#part_stats">statistics and clustering</a></li>
<li><a href="#part_misc">miscellaneous (constants, configuration)</a></li>
</ul>
<br>

<a name="part_classes"></a>
<b>Matrix, Vector, Cube and Field Classes</b>
<ul>
<table>
<tbody>
<tr><td><a href="#Mat">Mat&lt;<i>type</i>&gt;, mat, cx_mat</a></td><td>&nbsp;</td><td>dense matrix class</td></tr>
<tr><td><a href="#Col">Col&lt;<i>type</i>&gt;, colvec, vec</a></td><td>&nbsp;</td><td>dense column vector class</td></tr>
<tr><td><a href="#Row">Row&lt;<i>type</i>&gt;, rowvec</a></td><td>&nbsp;</td><td>dense row vector class</td></tr>
<tr><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><a href="#Cube">Cube&lt;<i>type</i>&gt;, cube, cx_cube</a></td><td>&nbsp;</td><td>dense cube class ("3D matrix")</td></tr>
<tr><td><a href="#field">field&lt;<i>object&nbsp;type</i>&gt;</a></td><td>&nbsp;</td><td>class for storing arbitrary objects in matrix-like or cube-like layouts</td></tr>
<tr><td><a href="#SpMat">SpMat&lt;<i>type</i>&gt;, sp_mat, sp_cx_mat</a></td><td>&nbsp;</td><td>sparse matrix class</td></tr>
<tr><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><a href="#operators">operators</a></td><td>&nbsp;</td><td><code><big>+</big>&nbsp; <big>&minus;</big>&nbsp; <big>*</big>&nbsp; %&nbsp; /&nbsp; ==&nbsp; !=&nbsp; &lt;=&nbsp; &gt;=&nbsp; &lt;&nbsp; &gt;&nbsp; &amp;&amp;&nbsp; ||</code></td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_membfns"></a>
<b>Member Functions &amp; Variables</b>
<ul>
<table>
<tbody>
<tr><td><a href="#attributes">attributes</a></td><td>&nbsp;</td><td>.n_rows, .n_cols, .n_elem, .n_slices, ...</td></tr>
<tr><td><a href="#element_access">element&nbsp;access</a></td><td>&nbsp;</td><td>element/object access via (), [] and .at()</td></tr>
<tr><td><a href="#element_initialisation">element&nbsp;initialisation</a></td><td>&nbsp;</td><td>set elements via initialiser lists</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#zeros_member">.zeros</a></td><td>&nbsp;</td><td>set all elements to zero</td></tr>
<tr><td><a href="#ones_member">.ones</a></td><td>&nbsp;</td><td>set all elements to one</td></tr>
<tr><td><a href="#eye_member">.eye</a></td><td>&nbsp;</td><td>set elements along main diagonal to one and off-diagonal elements to zero</td></tr>
<tr><td><a href="#randu_randn_member">.randu&nbsp;/&nbsp;.randn</a></td><td>&nbsp;</td><td>set all elements to random values</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#fill">.fill</a></td><td>&nbsp;</td><td>set all elements to specified value</td></tr>
<tr><td><a href="#imbue">.imbue</a></td><td>&nbsp;</td><td>imbue (fill) with values provided by functor or lambda function</td></tr>
<tr><td><a href="#clean">.clean</a></td><td>&nbsp;</td><td>replace elements below a threshold with zeros</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#replace">.replace</a></td><td>&nbsp;</td><td>replace specific elements with a new value</td></tr>
<tr><td><a href="#transform">.transform</a></td><td>&nbsp;</td><td>transform each element via functor or lambda function</td></tr>
<tr><td><a href="#for_each">.for_each</a></td><td>&nbsp;</td><td>apply a functor or lambda function to each element</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#set_size">.set_size</a></td><td>&nbsp;</td><td>change size without keeping elements (fast)</td></tr>
<tr><td><a href="#reshape_member">.reshape</a></td><td>&nbsp;</td><td>change size while keeping elements</td></tr>
<tr><td><a href="#resize_member">.resize</a></td><td>&nbsp;</td><td>change size while keeping elements and preserving layout</td></tr>
<tr><td><a href="#copy_size">.copy_size</a></td><td>&nbsp;</td><td>change size to be same as given object</td></tr>
<tr><td><a href="#reset">.reset</a></td><td>&nbsp;</td><td>change size to empty</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#submat">submatrix&nbsp;views</a></td><td>&nbsp;</td><td>read/write access to contiguous and non-contiguous submatrices</td></tr>
<tr><td><a href="#subcube">subcube&nbsp;views</a></td><td>&nbsp;</td><td>read/write access to contiguous and non-contiguous subcubes</td></tr>
<tr><td><a href="#subfield">subfield&nbsp;views</a></td><td>&nbsp;</td><td>read/write access to contiguous subfields</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#diag">.diag</a></td><td>&nbsp;</td><td>read/write access to matrix diagonals</td></tr>
<tr><td><a href="#each_colrow">.each_col&nbsp;/&nbsp;.each_row</a></td><td>&nbsp;</td><td>repeated operations on each column or row of matrix (aka "broadcasting")</td></tr>
<tr><td><a href="#each_slice">.each_slice</a></td><td>&nbsp;</td><td>repeated operations on each slice of cube (aka "broadcasting")</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#set_imag">.set_imag&nbsp;/&nbsp;.set_real</a></td><td>&nbsp;</td><td>set imaginary/real part</td></tr>
<tr><td><a href="#insert">.insert_rows/cols/slices</a></td><td>&nbsp;</td><td>insert vector/matrix/cube at specified row/column/slice</td></tr>
<tr><td><a href="#shed">.shed_rows/cols/slices</a></td><td>&nbsp;</td><td>remove specified rows/columns/slices</td></tr>
<tr><td><a href="#swap_rows">.swap_rows/cols</a></td><td>&nbsp;</td><td>swap specified rows or columns</td></tr>
<tr><td><a href="#swap">.swap</a></td><td>&nbsp;</td><td>swap contents with given object</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#memptr">.memptr</a></td><td>&nbsp;</td><td>raw pointer to memory</td></tr>
<tr><td><a href="#colptr">.colptr</a></td><td>&nbsp;</td><td>raw pointer to memory used by specified column</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#iterators_mat">iterators&nbsp;(matrices)</a></td><td>&nbsp;</td><td>iterators and associated member functions for dense matrices and vectors</td></tr>
<tr><td><a href="#iterators_cube">iterators&nbsp;(cubes)</a></td><td>&nbsp;</td><td>iterators and associated member functions for cubes</td></tr>
<tr><td><a href="#iterators_spmat">iterators&nbsp;(sparse matrices)</a></td><td>&nbsp;</td><td>iterators and associated member functions for sparse matrices</td></tr>
<tr><td><a href="#iterators_submat">iterators&nbsp;(submatrices)</a></td><td>&nbsp;</td><td>iterators and associated member functions for submatrices &amp; subcubes</td></tr>
<tr><td><a href="#compat_container_fns">compat.&nbsp;container&nbsp;functions</a></td><td>&nbsp;</td><td>compatibility container functions</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#as_col_row">.as_col&nbsp;/&nbsp;.as_row&nbsp;</a></td><td>&nbsp;</td><td>return flattened matrix as column or row vector</td></tr>
<tr><td><a href="#t_st_members">.t&nbsp;/&nbsp;.st&nbsp;</a></td><td>&nbsp;</td><td>return matrix transpose</td></tr>
<tr><td><a href="#i_member">.i&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</a></td><td>&nbsp;</td><td>return inverse of square matrix</td></tr>
<tr><td><a href="#min_and_max_member">.min&nbsp;/&nbsp;.max</a></td><td>&nbsp;</td><td>return extremum value</td></tr>
<tr><td><a href="#index_min_and_index_max_member">.index_min&nbsp;/&nbsp;.index_max</a></td><td>&nbsp;</td><td>return index of extremum value</td></tr>
<tr><td><a href="#eval_member">.eval</a></td><td>&nbsp;</td><td>force evaluation of delayed expression</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#in_range">.in_range</a></td><td>&nbsp;</td><td>check whether given location or span is valid</td></tr>
<tr><td><a href="#is_empty">.is_empty</a></td><td>&nbsp;</td><td>check whether object is empty</td></tr>
<tr><td><a href="#is_vec">.is_vec</a></td><td>&nbsp;</td><td>check whether matrix is a vector</td></tr>
<tr><td><a href="#is_sorted">.is_sorted</a></td><td>&nbsp;</td><td>check whether vector or matrix is sorted</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#is_trimat">.is_trimatu / .is_trimatl</a></td><td>&nbsp;</td><td>check whether matrix is upper/lower triangular</td></tr>
<tr><td><a href="#is_diagmat">.is_diagmat</a></td><td>&nbsp;</td><td>check whether matrix is diagonal</td></tr>
<tr><td><a href="#is_square">.is_square</a></td><td>&nbsp;</td><td>check whether matrix is square sized</td></tr>
<tr><td><a href="#is_symmetric">.is_symmetric</a></td><td>&nbsp;</td><td>check whether matrix is symmetric</td></tr>
<tr><td><a href="#is_hermitian">.is_hermitian</a></td><td>&nbsp;</td><td>check whether matrix is hermitian</td></tr>
<tr><td><a href="#is_sympd">.is_sympd</a></td><td>&nbsp;</td><td>check whether matrix is symmetric/hermitian positive definite</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#is_zero">.is_zero</a></td><td>&nbsp;</td><td>check whether all elements are zero</td></tr>
<tr><td><a href="#is_finite">.is_finite</a></td><td>&nbsp;</td><td>check whether all elements are finite</td></tr>
<tr><td><a href="#has_inf">.has_inf</a></td><td>&nbsp;</td><td>check whether any element is +-Inf</td></tr>
<tr><td><a href="#has_nan">.has_nan</a></td><td>&nbsp;</td><td>check whether any element is NaN</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#print">.print</a></td><td>&nbsp;</td><td>print object to <i>std::cout</i> or user specified stream</td></tr>
<tr><td><a href="#raw_print">.raw_print</a></td><td>&nbsp;</td><td>print object without formatting</td></tr>
<tr><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td><td><small><small>&nbsp;</small></small></td></tr>
<tr><td><a href="#save_load_mat">.save/.load&nbsp;(matrices&nbsp;&amp;&nbsp;cubes)</a></td><td>&nbsp;</td><td>save/load matrices and cubes in files or streams</td></tr>
<tr><td><a href="#save_load_field">.save/.load&nbsp;(fields)</a></td><td>&nbsp;</td><td>save/load fields in files or streams</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_gen"></a>
<b>Generated Vectors/Matrices/Cubes</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#linspace">linspace</a></td><td>&nbsp;</td><td>generate vector with linearly spaced elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#logspace">logspace</a></td><td>&nbsp;</td><td>generate vector with logarithmically spaced elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#regspace">regspace</a></td><td>&nbsp;</td><td>generate vector with regularly spaced elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#randperm">randperm</a></td><td>&nbsp;</td><td>generate vector with random permutation of a sequence of integers</td></tr>
<tr><td><a href="#eye_standalone">eye</a></td><td>&nbsp;</td><td>generate identity matrix</td></tr>
<tr><td><a href="#ones_standalone">ones</a></td><td>&nbsp;</td><td>generate object filled with ones</td></tr>
<tr><td><a href="#zeros_standalone">zeros</a></td><td>&nbsp;</td><td>generate object filled with zeros</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#randu_randn_standalone">randu&nbsp;/&nbsp;randn</a></td><td>&nbsp;</td><td>generate object with random values (uniform and normal distributions)</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#randg">randg</a></td><td>&nbsp;</td><td>generate object with random values (gamma distribution)</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#randi">randi</a></td><td>&nbsp;</td><td>generate object with random integer values in specified interval</td></tr>
<tr><td><a href="#speye">speye</a></td><td>&nbsp;</td><td>generate sparse identity matrix</td></tr>
<tr><td><a href="#spones">spones</a></td><td>&nbsp;</td><td>generate sparse matrix with non-zero elements set to one</td></tr>
<tr><td><a href="#sprandu_sprandn">sprandu&nbsp;/&nbsp;sprandn</a></td><td>&nbsp;</td><td>generate sparse matrix with non-zero elements set to random values</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#toeplitz">toeplitz</a></td><td>&nbsp;</td><td>generate Toeplitz matrix</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_fns"></a>
<b>Functions of Vectors/Matrices/Cubes</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#abs">abs</a></td><td>&nbsp;</td><td>obtain magnitude of each element</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#accu">accu</a></td><td>&nbsp;</td><td>accumulate (sum) all elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#affmul">affmul</a></td><td>&nbsp;</td><td>affine matrix multiplication</td></tr>
<tr><td><a href="#all">all</a></td><td>&nbsp;</td><td>check whether all elements are non-zero, or satisfy a relational condition</td></tr>
<tr><td><a href="#any">any</a></td><td>&nbsp;</td><td>check whether any element is non-zero, or satisfies a relational condition</td></tr>
<tr><td><a href="#approx_equal">approx_equal</a></td><td>&nbsp;</td><td>approximate equality</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#arg">arg</a></td><td>&nbsp;</td><td>phase angle of each element</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#as_scalar">as_scalar</a></td><td>&nbsp;</td><td>convert 1x1 matrix to pure scalar</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#clamp">clamp</a></td><td>&nbsp;</td><td>obtain clamped elements according to given limits</td></tr>
<tr><td><a href="#cond">cond</a></td><td>&nbsp;</td><td>condition number of matrix</td></tr>
<tr><td><a href="#conj">conj</a></td><td>&nbsp;</td><td>obtain complex conjugate of each element</td></tr>
<tr><td><a href="#conv_to">conv_to</a></td><td>&nbsp;</td><td>convert between matrix types</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#cross">cross</a></td><td>&nbsp;</td><td>cross product</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#cumsum">cumsum</a></td><td>&nbsp;</td><td>cumulative sum</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#cumprod">cumprod</a></td><td>&nbsp;</td><td>cumulative product</td></tr>
<tr><td><a href="#det">det</a></td><td>&nbsp;</td><td>determinant</td></tr>
<tr><td><a href="#diagmat">diagmat</a></td><td>&nbsp;</td><td>generate diagonal matrix from given matrix or vector</td></tr>
<tr><td><a href="#diagvec">diagvec</a></td><td>&nbsp;</td><td>extract specified diagonal</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#diff">diff</a></td><td>&nbsp;</td><td>differences between adjacent elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#dot">dot&nbsp;/&nbsp;cdot&nbsp;/&nbsp;norm_dot</a></td><td>&nbsp;</td><td>dot product</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#eps">eps</a></td><td>&nbsp;</td><td>obtain distance of each element to next largest floating point representation</td></tr>
<tr><td><a href="#expmat">expmat</a></td><td>&nbsp;</td><td>matrix exponential</td></tr>
<tr><td><a href="#expmat_sym">expmat_sym</a></td><td>&nbsp;</td><td>matrix exponential of symmetric matrix</td></tr>
<tr><td><a href="#find">find</a></td><td>&nbsp;</td><td>find indices of non-zero elements, or elements satisfying a relational condition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#find_finite">find_finite</a></td><td>&nbsp;</td><td>find indices of finite elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#find_nonfinite">find_nonfinite</a></td><td>&nbsp;</td><td>find indices of non-finite elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#find_unique">find_unique</a></td><td>&nbsp;</td><td>find indices of unique elements</td></tr>
<tr><td><a href="#flip">fliplr&nbsp;/&nbsp;flipud</a></td><td>&nbsp;</td><td>flip matrix left to right or upside down</td></tr>
<tr><td><a href="#imag_real">imag / real</a></td><td>&nbsp;</td><td>extract imaginary/real part</td></tr>
<tr><td><a href="#ind2sub">ind2sub</a></td><td>&nbsp;</td><td>convert linear index to subscripts</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#index_min_and_index_max_standalone">index_min / index_max</a></td><td>&nbsp;</td><td>indices of extremum values</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#inplace_trans">inplace_trans</a></td><td>&nbsp;</td><td>in-place transpose</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#intersect">intersect</a></td><td>&nbsp;</td><td>find common elements in two vectors/matrices</td></tr>
<tr><td><a href="#join">join_rows / join_cols</a></td><td>&nbsp;</td><td>concatenation of matrices</td></tr>
<tr><td><a href="#join_slices">join_slices</a></td><td>&nbsp;</td><td>concatenation of cubes</td></tr>
<tr><td><a href="#kron">kron</a></td><td>&nbsp;</td><td>Kronecker tensor product</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#log_det">log_det</a></td><td>&nbsp;</td><td>log determinant</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#logmat">logmat</a></td><td>&nbsp;</td><td>matrix logarithm</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#logmat_sympd">logmat_sympd</a></td><td>&nbsp;</td><td>matrix logarithm of symmetric matrix</td></tr>
<tr><td><a href="#min_and_max">min&nbsp;/&nbsp;max</a></td><td>&nbsp;</td><td>return extremum values</td></tr>
<tr><td><a href="#nonzeros">nonzeros</a></td><td>&nbsp;</td><td>return non-zero values</td></tr>
<tr><td><a href="#norm">norm</a></td><td>&nbsp;</td><td>various norms of vectors and matrices</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#normalise">normalise</a></td><td>&nbsp;</td><td>normalise vectors to unit <i>p</i>-norm</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#prod">prod</a></td><td>&nbsp;</td><td>product of elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#powmat">powmat</a></td><td>&nbsp;</td><td>matrix power</td></tr>
<tr><td><a href="#rank">rank</a></td><td>&nbsp;</td><td>rank of matrix</td></tr>
<tr><td><a href="#rcond">rcond</a></td><td>&nbsp;</td><td>reciprocal of condition number</td></tr>
<tr><td><a href="#repelem">repelem</a></td><td>&nbsp;</td><td>replicate elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#repmat">repmat</a></td><td>&nbsp;</td><td>replicate matrix in block-like fashion</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#reshape">reshape</a></td><td>&nbsp;</td><td>change size while keeping elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#resize">resize</a></td><td>&nbsp;</td><td>change size while keeping elements and preserving layout</td></tr>
<tr><td><a href="#reverse">reverse</a></td><td>&nbsp;</td><td>reverse order of elements</td></tr>
<tr><td><a href="#roots">roots</a></td><td>&nbsp;</td><td>roots of polynomial</td></tr>
<tr><td><a href="#shift">shift</a></td><td>&nbsp;</td><td>shift elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#shuffle">shuffle</a></td><td>&nbsp;</td><td>randomly shuffle elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#size">size</a></td><td>&nbsp;</td><td>obtain dimensions of given object</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#sort">sort</a></td><td>&nbsp;</td><td>sort elements</td></tr>
<tr><td><a href="#sort_index">sort_index</a></td><td>&nbsp;</td><td>vector describing sorted order of elements</td></tr>
<tr><td><a href="#sqrtmat">sqrtmat</a></td><td>&nbsp;</td><td>square root of matrix</td></tr>
<tr><td><a href="#sqrtmat_sympd">sqrtmat_sympd</a></td><td>&nbsp;</td><td>square root of symmetric matrix</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#sum">sum</a></td><td>&nbsp;</td><td>sum of elements</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#sub2ind">sub2ind</a></td><td>&nbsp;</td><td>convert subscripts to linear index</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#symmat">symmatu&nbsp;/&nbsp;symmatl</a></td><td>&nbsp;</td><td>generate symmetric matrix from given matrix</td></tr>
<tr><td><a href="#trace">trace</a></td><td>&nbsp;</td><td>sum of diagonal elements</td></tr>
<tr><td><a href="#trans">trans</a></td><td>&nbsp;</td><td>transpose of matrix</td></tr>
<tr><td><a href="#trapz">trapz</a></td><td>&nbsp;</td><td>trapezoidal numerical integration</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#trimat">trimatu&nbsp;/&nbsp;trimatl</a></td><td>&nbsp;</td><td>copy upper/lower triangular part</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#trimat_ind">trimatu_ind&nbsp;/&nbsp;trimatl_ind</a></td><td>&nbsp;</td><td>obtain indices of upper/lower triangular part</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#unique">unique</a></td><td>&nbsp;</td><td>return unique elements</td></tr>
<tr><td><a href="#vectorise">vectorise</a></td><td>&nbsp;</td><td>flatten matrix into vector</td></tr>
<tr><td><a href="#misc_fns">misc&nbsp;functions</a></td><td>&nbsp;</td><td>miscellaneous element-wise functions:&nbsp;exp,&nbsp;log,&nbsp;pow,&nbsp;sqrt,&nbsp;round,&nbsp;sign,&nbsp;...</td></tr>
<tr><td><a href="#trig_fns">trig&nbsp;functions</a></td><td>&nbsp;</td><td>trigonometric element-wise functions:&nbsp;cos,&nbsp;sin,&nbsp;...</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_decompdense"></a>
<b>Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#chol">chol</a></td><td>&nbsp;</td><td>Cholesky decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#eig_sym">eig_sym</a></td><td>&nbsp;</td><td>eigen decomposition of dense symmetric/hermitian matrix</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#eig_gen">eig_gen</a></td><td>&nbsp;</td><td>eigen decomposition of dense general square matrix</td></tr>
<tr><td><a href="#eig_pair">eig_pair</a></td><td>&nbsp;</td><td>eigen decomposition for pair of general dense square matrices</td></tr>
<tr><td><a href="#hess">hess</a></td><td>&nbsp;</td><td>upper Hessenberg decomposition</td></tr>
<tr><td><a href="#inv">inv</a></td><td>&nbsp;</td><td>inverse of general square matrix</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#inv_sympd">inv_sympd</a></td><td>&nbsp;</td><td>inverse of symmetric positive definite matrix</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#lu">lu&nbsp;&nbsp;</a></td><td>&nbsp;</td><td>lower-upper decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#null">null</a></td><td>&nbsp;</td><td>orthonormal basis of null space</td></tr>
<tr><td><a href="#orth">orth</a></td><td>&nbsp;</td><td>orthonormal basis of range space</td></tr>
<tr><td><a href="#pinv">pinv</a></td><td>&nbsp;</td><td>pseudo-inverse</td></tr>
<tr><td><a href="#qr">qr&nbsp;&nbsp;</a></td><td>&nbsp;</td><td>QR decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#qr_econ">qr_econ</a></td><td>&nbsp;</td><td>economical QR decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#qz">qz&nbsp;&nbsp;</a></td><td>&nbsp;</td><td>generalised Schur decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#schur">schur</a></td><td>&nbsp;</td><td>Schur decomposition</td></tr>
<tr><td><a href="#solve">solve</a></td><td>&nbsp;</td><td>solve systems of linear equations</td></tr>
<tr><td><a href="#svd">svd</a></td><td>&nbsp;</td><td>singular value decomposition</td></tr>
<tr><td><a href="#svd_econ">svd_econ</a></td><td>&nbsp;</td><td>economical singular value decomposition</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#syl">syl</a></td><td>&nbsp;</td><td>Sylvester equation solver</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_decompsparse"></a>
<b>Decompositions, Factorisations and Equation Solvers (Sparse Matrices)</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#eigs_sym">eigs_sym</a></td><td>&nbsp;</td><td>limited number of eigenvalues &amp; eigenvectors of sparse symmetric real matrix</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#eigs_gen">eigs_gen</a></td><td>&nbsp;</td><td>limited number of eigenvalues &amp; eigenvectors of sparse general square matrix</td></tr>
<tr><td><a href="#spsolve">spsolve</a></td><td>&nbsp;</td><td>solve sparse systems of linear equations</td></tr>
<tr><td><a href="#svds">svds</a></td><td>&nbsp;</td><td>truncated svd: limited number of singular values &amp; singular vectors of sparse matrix</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_sigproc"></a>
<b>Signal &amp; Image Processing</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#conv">conv</a></td><td>&nbsp;</td><td>1D convolution</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#conv2">conv2</a></td><td>&nbsp;</td><td>2D convolution</td></tr>
<tr><td><a href="#fft">fft&nbsp;/&nbsp;ifft</a></td><td>&nbsp;</td><td>1D fast Fourier transform and its inverse</td></tr>
<tr><td><a href="#fft2">fft2&nbsp;/&nbsp;ifft2</a></td><td>&nbsp;</td><td>2D fast Fourier transform and its inverse</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#interp1">interp1</a></td><td>&nbsp;</td><td>1D interpolation</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#interp2">interp2</a></td><td>&nbsp;</td><td>2D interpolation</td></tr>
<tr><td><a href="#polyfit">polyfit</a></td><td>&nbsp;</td><td>find polynomial coefficients for data fitting</td></tr>
<tr><td><a href="#polyval">polyval</a></td><td>&nbsp;</td><td>evaluate polynomial</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_stats"></a>
<b>Statistics &amp; Clustering</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#stats_fns">stats&nbsp;functions</a></td><td>&nbsp;</td><td>mean, median, standard deviation, variance</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#cov">cov</a></td><td>&nbsp;</td><td>covariance</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#cor">cor</a></td><td>&nbsp;</td><td>correlation</td></tr>
<tr><td><a href="#hist">hist</a></td><td>&nbsp;</td><td>histogram of counts</td></tr>
<tr><td><a href="#histc">histc</a></td><td>&nbsp;</td><td>histogram of counts with user specified edges</td></tr>
<tr><td><a href="#quantile">quantile</a></td><td>&nbsp;</td><td>quantiles of a dataset</td></tr>
<tr><td><a href="#princomp">princomp</a></td><td>&nbsp;</td><td>principal component analysis (PCA)</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#normpdf">normpdf</a></td><td>&nbsp;</td><td>probability density function of normal distribution</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#log_normpdf">log_normpdf</a></td><td>&nbsp;</td><td>logarithm version of probability density function of normal distribution</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#normcdf">normcdf</a></td><td>&nbsp;</td><td>cumulative distribution function of normal distribution</td></tr>
<tr><td><a href="#mvnrnd">mvnrnd</a></td><td>&nbsp;</td><td>random vectors from multivariate normal distribution</td></tr>
<tr><td><a href="#chi2rnd">chi2rnd</a></td><td>&nbsp;</td><td>random numbers from chi-squared distribution</td></tr>
<tr><td><a href="#wishrnd">wishrnd</a></td><td>&nbsp;</td><td>random matrix from Wishart distribution</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#iwishrnd">iwishrnd</a></td><td>&nbsp;</td><td>random matrix from inverse Wishart distribution</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat">running_stat</a></td><td>&nbsp;</td><td>running statistics of scalars (one dimensional process/signal)</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat_vec">running_stat_vec</a></td><td>&nbsp;</td><td>running statistics of vectors (multi-dimensional process/signal)</td></tr>
<tr><td><a href="#kmeans">kmeans</a></td><td>&nbsp;</td><td>cluster data into disjoint sets</td></tr>
<tr><td><a href="#gmm_diag">gmm_diag/gmm_full</a></td><td>&nbsp;</td><td>model and evaluate data using Gaussian Mixture Models (GMMs)</td></tr>
</tbody>
</table>
</ul>
<br>

<a name="part_misc"></a>
<b>Miscellaneous</b>
<ul>
<table>
<tbody>
<tr style="background-color: #F5F5F5;"><td><a href="#constants">constants</a></td><td>&nbsp;</td><td>pi, inf, NaN, speed&nbsp;of&nbsp;light,&nbsp;...</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#wall_clock">wall_clock</a></td><td>&nbsp;</td><td>timer for measuring number of elapsed seconds</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#logging">logging&nbsp;of&nbsp;errors/warnings</a></td><td>&nbsp;</td><td>how to change the streams for displaying warnings and errors</td></tr>
<tr><td><a href="#uword">uword&nbsp;/&nbsp;sword</a></td><td>&nbsp;</td><td>shorthand for unsigned and signed integers</td></tr>
<tr><td><a href="#cx_double">cx_double&nbsp;/&nbsp;cx_float</a></td><td>&nbsp;</td><td>shorthand for std::complex&lt;double&gt; and std::complex&lt;float&gt;</td></tr>
<tr><td><a href="#syntax">Matlab/Armadillo&nbsp;syntax&nbsp;differences</a></td><td>&nbsp;</td><td>examples of Matlab syntax and conceptually corresponding Armadillo syntax</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#example_prog">example&nbsp;program</a></td><td>&nbsp;</td><td>short example program</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#config_hpp">config.hpp</a></td><td>&nbsp;</td><td>configuration options</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#api_additions">API&nbsp;additions</a></td><td>&nbsp;</td><td>API stability and list of API additions</td></tr>
<!--<tr><td><a href="#log_add">log_add</a></td><td>&nbsp;</td><td>TODO</td></tr>-->
<!--<tr><td><a href="#catching_exceptions">catching exceptions</a></td><td>&nbsp;</td><td>TODO</td></tr>-->
</tbody>
</table>
</ul>
<br>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Matrix, Vector, Cube and Field Classes</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="Mat"></a><b>Mat&lt;</b><i>type</i><b>&gt;</b>
<br><b>mat</b>
<br><b>cx_mat</b>
<ul>
<li>
Classes for dense matrices, with elements stored in <a href="https://en.wikipedia.org/wiki/Column_major">column-major ordering</a> (ie. column by column)
</li>
<br>
<li>
The root matrix class is <b>Mat&lt;</b><i>type</i><b>&gt;</b>, where <i>type</i> is one of:
<ul>
<li>
<i>float</i>, <i>double</i>, <i>std::complex&lt;float&gt;</i>, <i>std::complex&lt;double&gt;</i>,
<i>short</i>, <i>int</i>, <i>long</i>, and unsigned versions of <i>short</i>, <i>int</i>, <i>long</i>
</li>
</ul>
</li>
<br>
<li>
For convenience the following typedefs have been defined:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>mat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>dmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>fmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;float&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_mat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_dmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_fmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;<a href="#cx_double">cx_float</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>umat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;<a href="#uword">uword</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>imat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Mat&lt;<a href="#uword">sword</a>&gt;</code>
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
In this documentation the <i>mat</i> type is used for convenience;
it is possible to use other types instead, eg. <i>fmat</i>
</li>
<br>
<li>
Functions which use LAPACK or ATLAS (generally matrix decompositions) are only valid for the following types:
<i>mat</i>, <i>dmat</i>, <i>fmat</i>, <i>cx_mat</i>, <i>cx_dmat</i>, <i>cx_fmat</i>
</li>
<br>
<a name="constructors_mat"></a>
<li>
Constructors:
<ul>
<table>
<tbody>
<tr><td><code>mat()</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(<i>n_rows</i>, <i>n_cols</i>)</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>mat(<i>n_rows</i>, <i>n_cols</i>, <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>mat(size(<i>X</i>))</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>mat(size(<i>X</i>), <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>mat(mat)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(vec)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(rowvec)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(initializer_list)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(string)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>mat(std::vector)</code></td><td>&nbsp;</td><td>(treated as a column vector)</td></tr>
<tr><td><code>mat(sp_mat)</code></td><td>&nbsp;</td><td>(for converting a sparse matrix to a dense matrix)</td></tr>
<tr><td><code>cx_mat(mat,mat)</code></td><td>&nbsp;</td><td>(for constructing a complex matrix out of two real matrices)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
When using the <i>mat(n_rows, n_cols)</i> or <i>mat(size(X))</i> constructors, by default the memory is uninitialised (ie. may contain garbage);
memory can be explicitly initialised by specifying the <i>fill_type</i>,
which is one of:
<i>fill::zeros</i>,
<i>fill::ones</i>,
<i>fill::eye</i>,
<i>fill::randu</i>,
<i>fill::randn</i>,
<i>fill::none</i>,
with the following meanings:
<ul>
<table>
<tbody>
<tr><td><code>fill::zeros</code></td><td>&nbsp;=&nbsp;</td><td>set all elements to 0</td></tr>
<tr><td><code>fill::ones</code></td><td>&nbsp;=&nbsp;</td><td>set all elements to 1</td></tr>
<tr><td><code>fill::eye</code></td><td>&nbsp;=&nbsp;</td><td>set the elements along the main diagonal to 1 and off-diagonal elements to 0</td></tr>
<tr><td><code>fill::randu</code></td><td>&nbsp;=&nbsp;</td><td>set each element to a random value from a uniform distribution in the [0,1] interval</td></tr>
<tr><td><code>fill::randn</code></td><td>&nbsp;=&nbsp;</td><td>set each element to a random value from a normal/Gaussian distribution with zero mean and unit variance</td></tr>
<tr><td><code>fill::none</code></td><td>&nbsp;=&nbsp;</td><td>do not modify the elements</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
For the <i>mat(string)</i> constructor, the format is elements separated by spaces, and rows denoted by semicolons;
for example, the 2x2 identity matrix can be created using <code>"1&nbsp;0;&nbsp;0&nbsp;1"</code>.
<br>
<b>Caveat:</b> string based initialisation is slower than directly <a href="#element_access">setting the elements</a> or using <a href="#element_initialisation">element initialisation</a>.
</li>
<br>
<li>
Each instance of <i>mat</i> automatically allocates and releases internal memory.
All internally allocated memory used by an instance of <i>mat</i> is automatically released as soon as the instance goes out of scope.
For example, if an instance of <i>mat</i> is declared inside a function, it will be automatically destroyed at the end of the function.
To forcefully release memory at any point, use <a href="#reset">.reset()</a>; note that in normal use this is not required.
</li>
<br>
<a name="adv_constructors_mat"></a>
<li>
Advanced constructors:
<br>
<br>
<ul>
<code>mat(ptr_aux_mem, n_rows, n_cols, copy_aux_mem = true, strict = false)</code>
<br>
<br>
<ul>
Create a matrix using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the memory.
By default the matrix allocates its own memory and copies data from the auxiliary memory (for safety).
However, if <i>copy_aux_mem</i> is set to <i>false</i>,
the matrix will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
<br>
<br>
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
(ie. the matrix is directly using auxiliary memory)
<ul>
<li>
when <i>strict</i> is set to <i>false</i>, the matrix will use the auxiliary memory until a size change
</li>
<li>
when <i>strict</i> is set to <i>true</i>, the matrix will be bound to the auxiliary memory for its lifetime;
the number of elements in the matrix can't be changed
</li>
</ul>
</ul>
<br>
<code>mat(const ptr_aux_mem, n_rows, n_cols)</code>
<br>
<br>
<ul>
Create a matrix by copying data from read-only auxiliary memory,
where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
<a name="adv_constructors_mat_fixed"></a>
<br>
<code>mat::fixed&lt;n_rows, n_cols&gt;</code>
<br>
<br>
<ul>
Create a fixed size matrix, with the size specified via template arguments.
Memory for the matrix is reserved at compile time.
This is generally faster than dynamic memory allocation, but the size of the matrix can't be changed afterwards (directly or indirectly).
<br>
<br>
For convenience, there are several pre-defined typedefs for each matrix type
(where the types are: <i>umat</i>, <i>imat</i>, <i>fmat</i>, <i>mat</i>, <i>cx_fmat</i>, <i>cx_mat</i>).
The typedefs specify a square matrix size, ranging from 2x2 to 9x9.
The typedefs were defined by simply appending a two digit form of the size to the matrix type
-- for example, <i>mat33</i> is equivalent to <i>mat::fixed&lt;3,3&gt;</i>,
while <i>cx_mat44</i> is equivalent to <i>cx_mat::fixed&lt;4,4&gt;</i>.
</ul>
<br>
<code>mat::fixed&lt;n_rows, n_cols&gt;(const ptr_aux_mem)</code>
<br>
<br>
<ul>
Create a fixed size matrix, with the size specified via template arguments;
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
</ul>
</li>
<br>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
double x = A(1,2);

mat B = A + A;
mat C = A * B;
mat D = A % B;

cx_mat X(A,B);

B.zeros();
B.set_size(10,10);
B.ones(5,6);

B.print("B:");

mat::fixed&lt;5,6&gt; F;

double aux_mem[24];
mat H(&amp;aux_mem[0], 4, 6, false);  // use auxiliary memory
</pre>
</ul>
</li>
<br>
<li><b>Caveat:</b>
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below <b>will not</b> generate a 5x5 matrix with every element equal to 123.0:
<ul>
<pre>
mat A(5,5);  A = 123.0;
</pre>
</ul>
Use the following code instead:
<ul>
<pre>
mat A(5,5);  A.fill(123.0);
</pre>
</ul>
<br>
<li>
See also:
<ul>
<li><a href="#attributes">matrix attributes</a></li>
<li><a href="#element_access">accessing elements</a></li>
<li><a href="#element_initialisation">initialising elements</a></li>
<li><a href="#operators">math &amp; relational operators</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
<li><a href="#print">printing matrices</a></li>
<li><a href="#iterators_mat">element iterators</a></li>
<li><a href="#eval_member">.eval()</a></li>
<li><a href="#conv_to">conv_to()</a> (convert between matrix types)</li>
<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a> (cplusplus.com)
<li><a href="#Col">Col class</a></li>
<li><a href="#Row">Row class</a></li>
<li><a href="#Cube">Cube class</a></li>
<li><a href="#SpMat">SpMat class</a> (sparse matrix with compressed sparse column format)</li>
<li><a href="#config_hpp">config.hpp</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="Col"></a><b>Col&lt;</b><i>type</i><b>&gt;</b>
<br><b>vec</b>
<br><b>cx_vec</b>
<ul>
<li>
Classes for column vectors (dense matrices with one column)
</li>
<br>
<li>The <b>Col&lt;</b><i>type</i><b>&gt;</b> class is derived from the <b>Mat&lt;</b><i>type</i><b>&gt;</b> class
and inherits most of the member functions
</li>
<br>
<li>
For convenience the following typedefs have been defined:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>vec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>colvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>dvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>dcolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>fvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>fcolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;float&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_vec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_colvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_dvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_dcolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_fvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_fcolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;<a href="#cx_double">cx_float</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>uvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>ucolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;<a href="#uword">uword</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>ivec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top; text-align: right;">
      <code>icolvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Col&lt;<a href="#uword">sword</a>&gt;</code>
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
In this documentation, the <b><i>vec</i></b> and <b><i>colvec</i></b> types have the <b>same meaning</b> and are used <b>interchangeably</b>
</li>
<br>
<li>
In this documentation, the types <i>vec</i> or <i>colvec</i> are used for convenience; it is possible to use other types instead, eg.&nbsp;<i>fvec</i>, <i>fcolvec</i>
</li>
<br>
<li>
Functions which take <i>Mat</i> as input can generally also take <i>Col</i> as input;
main exceptions are functions which require square matrices
</li>
<br>
<li>
Constructors:
<ul>
<table>
<tbody>
<tr><td><code>vec()</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>vec(<i>n_elem</i>)</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>vec(<i>n_elem</i>, <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>vec(size(<i>X</i>))</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>vec(size(<i>X</i>), <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>vec(vec)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>vec(mat)</code></td><td>&nbsp;</td><td>(<i>std::logic_error</i> exception is thrown if the given matrix has more than one column)</td></tr>
<tr><td><code>vec(initializer_list)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>vec(string)</code></td><td>&nbsp;</td><td>(elements separated by spaces)</td></tr>
<tr><td><code>vec(std::vector)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>cx_vec(vec,vec)</code></td><td>&nbsp;</td><td>(for constructing a complex vector out of two real vectors)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
When using the <i>vec(n_elem)</i> or <i>vec(size(X))</i> constructors, by default the memory is uninitialised (ie. may contain garbage);
memory can be explicitly initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a>
</li>
<br>
<a name="adv_constructors_col"></a>
<li>
Advanced constructors:
<br>
<br>
<ul>
<code>vec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)</code>
<br>
<br>
<ul>
Create a column vector using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the memory.
By default the vector allocates its own memory and copies data from the auxiliary memory (for safety).
However, if <i>copy_aux_mem</i> is set to <i>false</i>,
the vector will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
<br>
<br>
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
(ie. the vector is directly using auxiliary memory)
<ul>
<li>
when <i>strict</i> is set to <i>false</i>, the vector will use the auxiliary memory until a size change
</li>
<li>
when <i>strict</i> is set to <i>true</i>, the vector will be bound to the auxiliary memory for its lifetime;
the number of elements in the vector can't be changed
</li>
</ul>
</ul>
<br>
<code>vec(const ptr_aux_mem, number_of_elements)</code>
<br>
<br>
<ul>
Create a column vector by copying data from read-only auxiliary memory,
where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
<a name="adv_constructors_col_fixed"></a>
<br>
<code>vec::fixed&lt;number_of_elements&gt;</code>
<br>
<br>
<ul>
Create a fixed size column vector, with the size specified via the template argument.
Memory for the vector is reserved at compile time.
This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).
<br>
<br>
For convenience, there are several pre-defined typedefs for each vector type
(where the types are: <i>uvec</i>, <i>ivec</i>, <i>fvec</i>, <i>vec</i>, <i>cx_fvec</i>, <i>cx_vec</i> as well as the corresponding <i>colvec</i> versions).
The pre-defined typedefs specify vector sizes ranging from 2 to 9.
The typedefs were defined by simply appending a single digit form of the size to the vector type
-- for example, <i>vec3</i> is equivalent to <i>vec::fixed&lt;3&gt;</i>,
while <i>cx_vec4</i> is equivalent to <i>cx_vec::fixed&lt;4&gt;</i>.
</ul>
<br>
<code>vec::fixed&lt;number_of_elements&gt;(const ptr_aux_mem)</code>
<br>
<br>
<ul>
Create a fixed size column vector, with the size specified via the template argument;
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
</ul>
</li>
<br>
<br>
<li>
Examples:
<ul>
<pre>
vec x(10);
vec y(10, fill::zeros);

mat A(10, 10, fill::randu);
vec z = A.col(5); // extract a column vector
</pre>
</ul>
</li>
<br>
<li><b>Caveat:</b>
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below <b>will not</b> generate a column vector with every element equal to 123.0:
<ul>
<pre>
vec a(5);  a = 123.0;
</pre>
</ul>
Use the following code instead:
<ul>
<pre>
vec a(5);  a.fill(123.0);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#element_initialisation">element initialisation</a></li>
<li><a href="#Mat">Mat class</a></li>
<li><a href="#Row">Row class</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="Row"></a>
<b>Row&lt;</b><i>type</i><b>&gt;</b>
<br><b>rowvec</b>
<br><b>cx_rowvec</b>
<ul>
<li>
Classes for row vectors (dense matrices with one row)
</li>
<br>
<li>The template <b>Row&lt;</b><i>type</i><b>&gt;</b> class is derived from the <b>Mat&lt;</b><i>type</i><b>&gt;</b> class
and inherits most of the member functions
</li>
<br>
<li>
For convenience the following typedefs have been defined:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>rowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>drowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>frowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;float&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_rowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_drowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_frowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;<a href="#cx_double">cx_float</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>urowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;<a href="#uword">uword</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>irowvec</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Row&lt;<a href="#uword">sword</a>&gt;</code>
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
In this documentation, the <i>rowvec</i> type is used for convenience;
it is possible to use other types instead, eg. <i>frowvec</i>
</li>
<br>
<li>
Functions which take <i>Mat</i> as input can generally also take <i>Row</i> as input.
Main exceptions are functions which require square matrices
</li>
<br>
<li>
Constructors:
<ul>
<table>
<tbody>
<tr><td><code>rowvec()</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>rowvec(<i>n_elem</i>)</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>rowvec(<i>n_elem</i>, <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>rowvec(size(<i>X</i>))</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>rowvec(size(<i>X</i>), <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>rowvec(rowvec)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>rowvec(mat)</code></td><td>&nbsp;</td><td>(<i>std::logic_error</i> exception is thrown if the given matrix has more than one row)</td></tr>
<tr><td><code>rowvec(initializer_list)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>rowvec(string)</code></td><td>&nbsp;</td><td>(elements separated by spaces)</td></tr>
<tr><td><code>rowvec(std::vector)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>cx_rowvec(rowvec,rowvec)</code></td><td>&nbsp;</td><td>(for constructing a complex row vector out of two real row vectors)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
When using the <i>rowvec(n_elem)</i> or <i>rowvec(size(X))</i> constructors, by default the memory is uninitialised (ie. may contain garbage);
memory can be explicitly initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a>
</li>
<br>
<a name="adv_constructors_row"></a>
<li>
Advanced constructors:
<br>
<br>
<ul>
<code>rowvec(ptr_aux_mem, number_of_elements, copy_aux_mem = true, strict = false)</code>
<br>
<br>
<ul>
Create a row vector using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the memory.
By default the vector allocates its own memory and copies data from the auxiliary memory (for safety).
However, if <i>copy_aux_mem</i> is set to <i>false</i>,
the vector will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
<br>
<br>
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
(ie. the vector is directly using auxiliary memory)
<ul>
<li>
when <i>strict</i> is set to <i>false</i>, the vector will use the auxiliary memory until a size change
</li>
<li>
when <i>strict</i> is set to <i>true</i>, the vector will be bound to the auxiliary memory for its lifetime;
the number of elements in the vector can't be changed
</li>
</ul>
</ul>
<br>
<code>rowvec(const ptr_aux_mem, number_of_elements)</code>
<br>
<br>
<ul>
Create a row vector by copying data from read-only auxiliary memory,
where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
<br>
<code>rowvec::fixed&lt;number_of_elements&gt;</code>
<br>
<br>
<ul>
Create a fixed size row vector, with the size specified via the template argument.
Memory for the vector is reserved at compile time.
This is generally faster than dynamic memory allocation, but the size of the vector can't be changed afterwards (directly or indirectly).
<br>
<br>
For convenience, there are several pre-defined typedefs for each vector type
(where the types are: <i>urowvec</i>, <i>irowvec</i>, <i>frowvec</i>, <i>rowvec</i>, <i>cx_frowvec</i>, <i>cx_rowvec</i>).
The pre-defined typedefs specify vector sizes ranging from 2 to 9.
The typedefs were defined by simply appending a single digit form of the size to the vector type
-- for example, <i>rowvec3</i> is equivalent to <i>rowvec::fixed&lt;3&gt;</i>,
while <i>cx_rowvec4</i> is equivalent to <i>cx_rowvec::fixed&lt;4&gt;</i>.
</ul>
<br>
<code>rowvec::fixed&lt;number_of_elements&gt;(const ptr_aux_mem)</code>
<br>
<br>
<ul>
Create a fixed size row vector, with the size specified via the template argument;
data is copied from auxiliary memory, where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
</ul>
</li>
<br>
<br>
<li>
Examples:
<ul>
<pre>
rowvec x(10);
rowvec y(10, fill::zeros);

mat    A(10, 10, fill::randu);
rowvec z = A.row(5); // extract a row vector
</pre>
</ul>
</li>
<br>
<li>
<b>Caveat:</b>
For mathematical correctness, scalars are treated as 1x1 matrices during initialisation.
As such, the code below <b>will not</b> generate a row vector with every element equal to 123.0:
<ul>
<pre>
rowvec r(5);  r = 123.0;
</pre>
</ul>
Use the following code instead:
<ul>
<pre>
rowvec r(5);  r.fill(123.0);
</pre>
</ul>
<br>
<li>See also:
<ul>
<li><a href="#element_initialisation">element initialisation</a></li>
<li><a href="#Mat">Mat class</a></li>
<li><a href="#Col">Col class</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="Cube"></a>
<b>Cube&lt;</b><i>type</i><b>&gt;</b>
<br><b>cube</b>
<br><b>cx_cube</b>
<ul>
<li>
Classes for cubes, also known as "3D matrices" or 3rd order tensors
</li>
<br>
<li>
The cube class is <b>Cube&lt;</b><i>type</i><b>&gt;</b>, where <i>type</i> is one of:
<ul>
<li>
<i>float</i>, <i>double</i>, <i>std::complex&lt;float&gt;</i>, <i>std::complex&lt;double&gt;</i>,
<i>short</i>, <i>int</i>, <i>long</i> and unsigned versions of <i>short</i>, <i>int</i>, <i>long</i>
</li>
</ul>
</li>
<br>
<li>
For convenience the following typedefs have been defined:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>dcube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>fcube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;float&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_cube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_dcube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>cx_fcube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;<a href="#cx_double">cx_float</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>ucube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;<a href="#uword">uword</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>icube</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>Cube&lt;<a href="#uword">sword</a>&gt;</code>
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
In this documentation the <i>cube</i> type is used for convenience;
it is possible to use other types instead, eg. <i>fcube</i>
</li>
<br>
<li>
Cube data is stored as a set of slices (matrices) stored contiguously within memory.
Within each slice, elements are stored with column-major ordering (ie. column by column)
</li>
<br>
<li>
Each slice can be interpreted as a matrix, hence functions which take <i>Mat</i> as input can generally also take cube slices as input
</li>
<br>
<a name="constructors_cube"></a>
<li>
Constructors:
<ul>
<table>
<tbody>
<code>cube()</code>
<tr><td><code>cube(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>)</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>cube(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>, <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>cube(size(<i>X</i>))</code></td><td>&nbsp;</td><td>(memory is not initialised)</td></tr>
<tr><td><code>cube(size(<i>X</i>), <i>fill_type</i>)</code></td><td>&nbsp;</td><td>(memory is initialised)</td></tr>
<tr><td><code>cube(cube)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>cx_cube(cube, cube)</code></td><td>&nbsp;</td><td>(for constructing a complex cube out of two real cubes)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
When using the <i>cube(n_rows, n_cols, n_slices)</i> or <i>cube(size(X))</i> constructors, by default the memory is uninitialised (ie. may contain garbage);
memory can be explicitly initialised by specifying the <i>fill_type</i>,
as per the <a href="#Mat">Mat class</a> (except for <i>fill::eye</i>)
</li>
<br>
<li>
Each instance of <i>cube</i> automatically allocates and releases internal memory.
All internally allocated memory used by an instance of <i>cube</i> is automatically released as soon as the instance goes out of scope.
For example, if an instance of <i>cube</i> is declared inside a function, it will be automatically destroyed at the end of the function.
To forcefully release memory at any point, use <a href="#reset">.reset()</a>; note that in normal use this is not required.
</li>
<br>
<a name="adv_constructors_cube"></a>
<li>
Advanced constructors:
<br>
<br>
<ul>
<code>cube::fixed&lt;n_rows, n_cols, n_slices&gt;</code>
<br>
<br>
<ul>
Create a fixed size cube, with the size specified via template arguments.
Memory for the cube is reserved at compile time.
This is generally faster than dynamic memory allocation, but the size of the cube can't be changed afterwards (directly or indirectly).
</ul>
<br>
<code>cube(ptr_aux_mem, n_rows, n_cols, n_slices, copy_aux_mem = true, strict = false)</code>
<br>
<br>
<ul>
Create a cube using data from writable auxiliary (external) memory, where <i>ptr_aux_mem</i> is a pointer to the memory.
By default the cube allocates its own memory and copies data from the auxiliary memory (for safety).
However, if <i>copy_aux_mem</i> is set to <i>false</i>,
the cube will instead directly use the auxiliary memory (ie. no copying);
this is faster, but can be dangerous unless you know what you are doing!
<br>
<br>
The <i>strict</i> parameter comes into effect only when <i>copy_aux_mem</i> is set to <i>false</i>
(ie. the cube is directly using auxiliary memory)
<ul>
<li>
when <i>strict</i> is set to <i>false</i>, the cube will use the auxiliary memory until a size change
</li>
<li>
when <i>strict</i> is set to <i>true</i>, the cube will be bound to the auxiliary memory for its lifetime;
the number of elements in the cube can't be changed
</li>
</ul>
</ul>
<br>
<code>cube(const ptr_aux_mem, n_rows, n_cols, n_slices)</code>
<br>
<br>
<ul>
Create a cube by copying data from read-only auxiliary memory,
where <i>ptr_aux_mem</i> is a pointer to the memory
</ul>
</ul>
</li>
<br>
<br>
<li>
Examples:
<ul>
<pre>
cube x(1, 2, 3);
cube y(4, 5, 6, fill::randu);

mat A = y.slice(1);  // extract a slice from the cube
                     // (each slice is a matrix)

mat B(4, 5, fill::randu);
y.slice(2) = B;     // set a slice in the cube

cube q = y + y;     // cube addition
cube r = y % y;     // element-wise cube multiplication

cube::fixed&lt;4,5,6&gt; f;
f.ones();
</pre>
</ul>
</li>
<br>
<li>
<b>Caveats:</b>
<br>
<br>
<ul>
<li>
The size of individual slices can't be changed.
For example, the following <b>will not</b> work:
<ul>
<pre>
cube c(5,6,7);
c.slice(0) = randu&lt;mat&gt;(10,20); // wrong size
</pre>
</ul>
</li>
<li>
For mathematical correctness, scalars are treated as 1x1x1 cubes during initialisation.
As such, the code below <b>will not</b> generate a cube with every element equal to 123.0:
<ul>
<pre>
cube c(5,6,7);  c = 123.0;
</pre>
</ul>
Use the following code instead:
<ul>
<pre>
cube c(5,6,7);  c.fill(123.0);
</pre>
</ul>
<br>
</ul>
<li>
See also:
<ul>
<li><a href="#attributes">cube attributes</a></li>
<li><a href="#element_access">accessing elements</a></li>
<li><a href="#operators">math &amp; relational operators</a></li>
<li><a href="#subcube">subcube views and slices</a></li>
<li><a href="#save_load_mat">saving &amp; loading cubes</a></li>
<li><a href="#iterators_cube">element iterators</a></li>
<li><a href="#field">field class</a></li>
<li><a href="#Mat">Mat class</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="field"></a>
<b>field&lt;</b><i>object_type</i><b>&gt;</b>
<ul>
<li>
Class for storing arbitrary objects in matrix-like or cube-like layouts
</li>
<br>
<li>
Somewhat similar to a matrix or cube, but instead of each element being a scalar,
each element can be a vector, or matrix, or cube
</li>
<br>
<li>
Each element can have an arbitrary size (eg. in a field of matrices, each matrix can have a different size)
</li>
<br>
<li>
Constructors, where <i>object_type</i> is another class, eg. <i>vec</i>, <i>mat</i>, <i>std::string</i>, etc:
<ul>
<table>
<tbody>
<tr><td><code>field&lt;<i>object_type</i>&gt;()</code></td></tr>
<tr><td><code>field&lt;<i>object_type</i>&gt;(<i>n_elem</i>)</code></td></tr>
<tr><td><code>field&lt;<i>object_type</i>&gt;(<i>n_rows</i>, <i>n_cols</i>)</code></td></tr>
<tr><td><code>field&lt;<i>object_type</i>&gt;(<i>n_rows</i>, <i>n_cols</i>, <i>n_slices</i>)</code></td></tr>
<tr><td><code>field&lt;<i>object_type</i>&gt;(size(<i>X</i>))</code></td></tr>
<tr><td><code>field&lt;<i>object_type</i>&gt;(field&lt;<i>object_type</i>&gt;)</code></td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
<b>Caveat</b>: to store a set of matrices of the same size, the <a href="#Cube">Cube</a> class is more efficient
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = randn(2,3);
mat B = randn(4,5);

field&lt;mat&gt; F(2,1);
F(0,0) = A;
F(1,0) = B; 

F.print("F:");

F.save("mat_field");
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#attributes">field attributes</a></li>
<li><a href="#subfield">subfield views</a></li>
<li><a href="#save_load_field">saving/loading fields</a></li>
<li><a href="#Cube">Cube class</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="SpMat"></a><b>SpMat&lt;</b><i>type</i><b>&gt;</b>
<br><b>sp_mat</b>
<br><b>sp_cx_mat</b>
<ul>
<li>
Classes for sparse matrices; intended for storing very large matrices, where the vast majority of elements are zero
</li>
<br>
<li>
The root sparse matrix class is <b>SpMat&lt;</b><i>type</i><b>&gt;</b>, where <i>type</i> is one of:
<ul>
<li>
<i>float</i>, <i>double</i>, <i>std::complex&lt;float&gt;</i>, <i>std::complex&lt;double&gt;</i>,
<i>short</i>, <i>int</i>, <i>long</i> and unsigned versions of <i>short</i>, <i>int</i>, <i>long</i>
</li>
</ul>
</li>
<br>
<li>
For convenience the following typedefs have been defined:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_mat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_dmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;double&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_fmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;float&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_cx_mat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_cx_dmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;<a href="#cx_double">cx_double</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_cx_fmat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;<a href="#cx_double">cx_float</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_umat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;<a href="#uword">uword</a>&gt;</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <code>sp_imat</code>
      </td>
      <td style="vertical-align: top;">
      &nbsp;=&nbsp;
      </td>
      <td style="vertical-align: top;">
      <code>SpMat&lt;<a href="#uword">sword</a>&gt;</code>
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
In this documentation the <i>sp_mat</i> type is used for convenience;
it is possible to use other types instead, eg. <i>sp_fmat</i>
</li>
<br>
<a name="constructors_sp_mat"></a>
<li>
Constructors:
<ul>
<table>
<tbody>
<tr><td><code>sp_mat()</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>sp_mat(<i>n_rows</i>, <i>n_cols</i>)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>sp_mat(size(<i>X</i>))</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>sp_mat(sp_mat)</code></td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td><code>sp_mat(mat)</code></td><td>&nbsp;</td><td>(for converting a dense matrix to a sparse matrix)</td></tr>
<tr><td><code>sp_cx_mat(sp_mat,sp_mat)</code></td><td>&nbsp;</td><td>(for constructing a complex matrix out of two real matrices)</td></tr>
</tbody>
</table>
</ul>
<br>
<li>
All elements are treated as zero by default (ie. the matrix is initialised to contain zeros)
</li>
<br>
<li>
Non-zero elements are stored in <a href="http://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column (CSC) format</a> (ie. column-major ordering);
zero-valued elements are never stored
</li>
<br>
<li>
This class behaves in a similar manner to the <a href="#Mat">Mat</a> class;
however, member functions which set all elements to non-zero values (and hence do not make sense for sparse matrices) have been deliberately omitted;
examples of omitted functions: <a href="#fill">.fill()</a>, <a href="#ones_member">.ones()</a>, +=&nbsp;scalar, etc.
</li>
<br>
<li>
<a name="batch_constructors_sp_mat"></a>
Batch insertion constructors:
<ul>
<li>form&nbsp;1: <code>sp_mat(<i>locations</i>, <i>values</i>, <i>sort_locations = true</i>)</code></li>
<li>form&nbsp;2: <code>sp_mat(<i>locations</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>sort_locations&nbsp;=&nbsp;true</i>, <i>check_for_zeros&nbsp;=&nbsp;true</i>)</code></li>
<li>form&nbsp;3: <code>sp_mat(<i>add_values</i>, <i>locations</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>, <i>sort_locations&nbsp;=&nbsp;true</i>, <i>check_for_zeros&nbsp;=&nbsp;true</i>)</code></li>
<li>form&nbsp;4: <code>sp_mat(<i>rowind</i>, <i>colptr</i>, <i>values</i>, <i>n_rows</i>, <i>n_cols</i>)</code></li>
<br>
<ul>
<li>
For forms&nbsp;1,&nbsp;2,&nbsp;3,
<i>locations</i> is a dense matrix of type <i>umat</i>, with a size of <i>2</i>&nbsp;x&nbsp;<i>N</i>, where <i>N</i> is the number of values to be inserted;
the location of the <i>i</i>-th element is specified by the contents of the <i>i</i>-th column of the <i>locations</i> matrix,
where the row is in <i>locations(0,i)</i>, and the column is in <i>locations(1,i)</i>
</li>
<br>
<li>
For form&nbsp;4,
<i>rowind</i> is a dense column vector of type <i>uvec</i> containing the row indices of the values to be inserted,
and
<i>colptr</i> is a dense column vector of type <i>uvec</i> (with length <i>n_cols&nbsp;+&nbsp;1</i>) containing indices of <i>values</i> corresponding to the start of new columns;
the vectors correspond to the arrays used by the <a href="http://en.wikipedia.org/wiki/Sparse_matrix">compressed sparse column format</a>;
this form is useful for copying data from other CSC sparse matrix containers
</li>
<br>
<li>
For all forms, <i>values</i> is a dense column vector containing the values to be inserted;
it must have the same element type as the sparse matrix.
For forms&nbsp;1 and&nbsp;2, the value in <i>values[i]</i> will be inserted at the location specified by the <i>i</i>-th column of the <i>locations</i> matrix.
</li>
<br>
<li>
For form&nbsp;3,
<i>add_values</i> is either <i>true</i> or <i>false</i>; when set to <i>true</i>, identical locations are allowed, and the values at identical locations are added 
</li>
<br>
<li>
The size of the constructed matrix is either 
automatically determined from the maximal locations in the <i>locations</i> matrix (form&nbsp;1),
or
manually specified via <i>n_rows</i> and <i>n_cols</i> (forms&nbsp;2,&nbsp;3,&nbsp;4)
</li>
<br>
<li>
If <i>sort_locations</i> is set to <i>false</i>, the <i>locations</i> matrix is assumed to contain locations that are already sorted according to column-major ordering; do not set this to <i>false</i> unless you know what you are doing!
</li>
<br>
<li>
If <i>check_for_zeros</i> is set to <i>false</i>, the <i>values</i> vector is assumed to contain no zero values; do not set this to <i>false</i> unless you know what you are doing!
</li>
</ul>
</ul>
<br>
<li>
The following subset of operations &amp; functions is available for sparse matrices:
<ul>
<li>fundamental arithmetic <a href="#operators">operations</a> (such as addition and multiplication)</li>
<li><a href="#submat">submatrix views</a>: most contiguous forms and the non-contiguous form of <i>X.cols(vector_of_column_indices)</i></li>
<li><a href="#diag">diagonal views</a></li>
<li><a href="#save_load_mat">saving and loading</a> (using <i>arma_binary</i>, <i>coord_ascii</i>, and <i>csv_ascii</i> formats)</li>
<li>element-wise functions: <a href="#abs">abs()</a>, <a href="#misc_fns">ceil()</a>, <a href="#conj">conj()</a>, <a href="#misc_fns">floor()</a>, <a href="#imag_real">imag()</a>, <a href="#imag_real">real()</a>, <a href="#misc_fns">round()</a>, <a href="#misc_fns">sign()</a>, <a href="#misc_fns">sqrt()</a>, <a href="#misc_fns">square()</a>, <a href="#misc_fns">trunc()</a></li>
<li>scalar functions of matrices: <a href="#accu">accu()</a>, <a href="#as_scalar">as_scalar()</a>, <a href="#dot">dot()</a>, <a href="#norm">norm()</a>, <a href="#trace">trace()</a></li>
<li>vector valued functions of matrices: <a href="#diagvec">diagvec()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a>, <a href="#nonzeros">nonzeros()</a>, <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#stats_fns">var()</a>, <a href="#vectorise">vectorise()</a></li>
<li>matrix valued functions of matrices: <a href="#clamp">clamp()</a>, <a href="#diagmat">diagmat()</a>, <a href="#flip">flipud()/fliplr()</a>, <a href="#join">join_rows()</a>, <a href="#join">join_cols()</a>, <a href="#kron">kron()</a>, <a href="#normalise">normalise()</a>, <a href="#repelem">repelem()</a>, <a href="#repmat">repmat()</a>, <a href="#reshape">reshape()</a>, <a href="#resize">resize()</a>, <a href="#reverse">reverse()</a>, <a href="#symmat">symmatu()/symmatl()</a>, <a href="#trimat">trimatu()/trimatl()</a>, <a href="#t_st_members">.t()</a>, <a href="#trans">trans()</a></li>
<li>generated matrices: <a href="#speye">speye()</a>, <a href="#spones">spones()</a>, <a href="#sprandu_sprandn">sprandu()</a>, <a href="#sprandu_sprandn">sprandn()</a>, <a href="#zeros_standalone">zeros()</a></li>
<li>eigen and svd decomposition: <a href="#eigs_sym">eigs_sym()</a>, <a href="#eigs_gen">eigs_gen()</a>, <a href="#svds">svds()</a></li>
<li>solution of sparse linear systems: <a href="#spsolve">spsolve()</a>
<li>miscellaneous: <a href="#approx_equal">approx_equal()</a>, <a href="#element_access">element access</a>, <a href="#iterators_spmat">element iterators</a>, <a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a>, <a href="#for_each">.for_each()</a>, <a href="#print">.print()</a>, <a href="#clean">.clean()</a>, <a href="#replace">.replace()</a>, <a href="#transform">.transform()</a>, <a href="#is_finite">.is_finite()</a>, <a href="#is_symmetric">.is_symmetric()</a>, <a href="#is_hermitian">.is_hermitian()</a>, <a href="#is_trimat">.is_trimatu()</a>, <a href="#is_trimat">.is_trimatl()</a>, <a href="#is_diagmat">.is_diagmat()</a></li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = sprandu(1000, 2000, 0.01);
sp_mat B = sprandu(2000, 1000, 0.01);

sp_mat C = 2*B;
sp_mat D = A*C;

sp_mat E(1000,1000);
E(1,2) = 123;


// batch insertion of 3 values at
// locations (1, 2), (7, 8), (9, 9)

umat locations = { { 1, 7, 9 },
                   { 2, 8, 9 } };

vec values = { 1.0, 2.0, 3.0 };

sp_mat X(locations, values);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#element_access">element access</a></li>
<li><a href="#iterators_spmat">element iterators (sparse matrices)</a></li>
<li><a href="#print">printing matrices</a></li>
<!--
<li><a href="#SpCol">SpCol class</a> (TODO: add to documentation)</li>
<li><a href="#SpRow">SpRow class</a> (TODO: add to documentation)</li>
-->
<li><a href="http://en.wikipedia.org/wiki/Sparse_matrix">Sparse Matrix in Wikipedia</a></li>
<li><a href="#Mat">Mat class</a> (dense matrix)</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="operators"></a>
<b>operators:&nbsp; <code><big>+</big>&nbsp; <big>&minus;</big>&nbsp; <big>*</big>&nbsp; %&nbsp; /&nbsp; ==&nbsp; !=&nbsp; &lt;=&nbsp; &gt;=&nbsp; &lt;&nbsp; &gt;&nbsp; &amp;&amp;&nbsp; ||</code></b>
<ul>
<li>
Overloaded operators for <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> classes
</li>
<br>
<li>
Operations:
<br>
<br>
<ul>
<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><code><b><big>+</big></b></code></td>
      <td style="vertical-align: top;">&nbsp;&nbsp;&nbsp;<br>
      </td>
      <td style="vertical-align: top;">addition of two objects</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b><big>&minus;</big></b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">subtraction of one object from another or negation of an object</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b><big>*</big></b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">matrix multiplication of two objects; not applicable to the <i>Cube</i> class unless multiplying by a scalar</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>%</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;"><a name="schur_product"></a>element-wise multiplication of two objects (Schur product)</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>/</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise division of an object by another object or a scalar</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>==</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise equality evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>!=</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise non-equality evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>&gt;=</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise "greater than or equal to" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>&lt;=</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise "less than or equal to" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>&gt;</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise "greater than" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>&lt;</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise "less than" evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>&amp;&amp;</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise logical AND evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><code><b>||</b></code></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td style="vertical-align: top;">element-wise logical OR evaluation of two objects; generates a matrix/cube of type <i>umat</i>/<i>ucube</i></td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
For element-wise relational and logical operations
(ie. <code><b>==</b></code>, <code><b>!=</b></code>, <code><b>&gt;=</b></code>, <code><b>&lt;=</b></code>, <code><b>&gt;</b></code>, <code><b>&lt;</b></code>, <code><b>&amp;&amp;</b></code>, <code><b>||</b></code>)
each element in the generated object is either 0 or 1, depending on the result of the operation
</li>
<br>
<li>
<b>Caveat:</b> operators involving equality comparison (ie. <code><b>==</b></code>, <code><b>!=</b></code>, <code><b>&gt;=</b></code>, <code><b>&lt;=</b></code>)
are not recommended for matrices of type <i>mat</i> or <i>fmat</i>, due to the necessarily <a href="https://en.wikipedia.org/wiki/Floating_point">limited precision</a> of the underlying element types;
consider using <a href="#approx_equal">approx_equal()</a> instead
</li>
<br>
<li>
If the <code><b>+</b></code>, <code><b>&minus;</b></code> and <code><b>%</b></code> operators are chained, Armadillo aims to avoid the generation of temporaries;
no temporaries are generated if all given objects are of the same type and size
</li>
<br>
<li>
If the <code><b>*</b></code> operator is chained, Armadillo aims to find an efficient ordering of the matrix multiplications
</li>
<br>
<li>
For "broadcasting" operations, use <a href="#each_colrow">.each_col()</a> and <a href="#each_colrow">.each_row()</a>
</li>
<br>
<li>
A <i>std::logic_error</i> exception is thrown if incompatible object sizes are used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 10, fill::randu);
mat B(5, 10, fill::randu);
mat C(10, 5, fill::randu);

mat P = A + B;
mat Q = A - B;
mat R = -B;
mat S = A / 123.0;
mat T = A % B;
mat U = A * C;

// V is constructed without temporaries
mat V = A + B + A + B;

imat AA = "1 2 3; 4 5 6; 7 8 9;";
imat BB = "3 2 1; 6 5 4; 9 8 7;";

// compare elements
umat ZZ = (AA >= BB);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#approx_equal">approx_equal()</a></li>
<li><a href="#powmat">powmat()</a></li>
<li><a href="#any">any()</a></li>
<li><a href="#all">all()</a></li>
<li><a href="#affmul">affmul()</a></li>
<li><a href="#accu">accu()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a> &nbsp;&nbsp; (vector operations repeated on each column or row)</li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a> &nbsp; (exp, log, pow, sqrt, square, round, ...)</li>
<li><a href="https://en.wikipedia.org/wiki/Floating_point">floating point representation in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/Floating-PointRepresentation.html">floating point representation in MathWorld</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Member Functions &amp; Variables</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="attributes"></a>
<b>attributes</b>
<ul>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td>
<code><b>.n_rows</b></code>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td>
number of rows; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i>
</td>
</tr>
<tr>
<td>
<code><b>.n_cols</b></code>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td>
number of columns; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i>
</td>
</tr>
<tr>
<td>
<code><b>.n_elem</b></code>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td>
total number of elements; present in <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i> and <i>SpMat</i>
</td>
</tr>
<tr>
<td>
<code><b>.n_slices</b></code>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td>
number of slices; present in <i>Cube</i> and <i>field</i>
</td>
</tr>
<tr>
<td>
<code><b>.n_nonzero</b></code>
</td>
<td>&nbsp;&nbsp;&nbsp;</td>
<td>
number of non-zero elements; present in <i>SpMat</i>
</td>
</tr>
</tbody>
</table>
</ul>
<ul>
<li>The variables are of type <a href="#uword">uword</a></li>
<br>
<li>
The variables are read-only;
to change the size, use
<a href="#set_size">.set_size()</a>,
<a href="#copy_size">.copy_size()</a>,
<a href="#zeros_member">.zeros()</a>,
<a href="#ones_member">.ones()</a>,
or
<a href="#reset">.reset()</a>
</li>
<br>
<li>
For the <i>Col</i> and <i>Row</i> classes, <i>n_elem</i> also indicates vector length</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4,5);
cout &lt;&lt; "X has " &lt;&lt; X.n_cols &lt;&lt; " columns" &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#copy_size">.copy_size()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#ones_member">.ones()</a></li>
<li><a href="#reset">.reset()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="element_access"></a>
<b>element/object access via (), [] and .at()</b>
<ul>
<li>
Provide access to individual elements or objects stored in a container object
(ie. <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i>)<br>
<br>
<ul>
<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
<tbody>
  <tr>
    <td style="vertical-align: top;">
    <code>(n)</code>
    </td>
    <td style="vertical-align: top;">&nbsp;<br>
    </td>
    <td style="vertical-align: top;">
For <i>vec</i> and <i>rowvec</i>, access the <i>n</i>-th element.
For <i>mat</i>, <i>cube</i> and <i>field</i>, access the <i>n</i>-th element/object under the assumption of a flat layout,
with column-major ordering of data (ie. column by column).
A&nbsp;<i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed.
  </td>
</tr>
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
  <td style="vertical-align: top;">
  <code>.at(n)</code>&nbsp;&nbsp;or&nbsp;&nbsp;<code>[n]</code>&nbsp;
  </td>
  <td style="vertical-align: top;"><br>
  </td>
  <td style="vertical-align: top;">
As for <code>(n)</code>, but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged.
  </td>
</tr>
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
  <td style="vertical-align: top;">
  <code>(i,j)</code>
  </td>
  <td style="vertical-align: top;"><br>
  </td>
  <td style="vertical-align: top;">
For <i>mat</i> and <i>2D field</i> classes, access the element/object stored at the <i>i</i>-th row and <i>j</i>-th column.
A&nbsp;<i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed.
  </td>
</tr>
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
  <td style="vertical-align: top;">
  <code>.at(i,j)</code>
  </td>
  <td style="vertical-align: top;"><br>
  </td>
  <td style="vertical-align: top;">
As for <code>(i,j)</code>, but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged.
</td>
  <td style="vertical-align: top;"><br>
  </td>
</tr>
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
  <td style="vertical-align: top;">
  <code>(i,j,k)</code>
  </td>
  <td style="vertical-align: top;"><br>
  </td>
  <td style="vertical-align: top;">
For <i>cube</i> and <i>3D field</i> classes, access the element/object stored at the <i>i</i>-th row, <i>j</i>-th column and <i>k</i>-th slice.
A&nbsp;<i>std::logic_error</i> exception is thrown if the requested element is out of bounds.
The bounds check can be <a href="#element_access_bounds_check_note">optionally disabled</a> at compile-time to get more speed.
  </td>
</tr>
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr>
  <td style="vertical-align: top;">
  <code>.at(i,j,k)</code>
  </td>
  <td style="vertical-align: top;"><br>
  </td>
  <td style="vertical-align: top;">
As for <code>(i,j,k)</code>, but without a bounds check.
Not recommended for use unless your code has been thoroughly debugged.</td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<a name="element_access_bounds_check_note"></a>
<li>
The bounds checks used by the <code>(n)</code>, <code>(i,j)</code> and <code>(i,j,k)</code> element access forms
can be disabled by defining the <a href="#config_hpp_arma_no_debug">ARMA_NO_DEBUG</a> macro
before including the <i>armadillo</i> header file (eg. <code>#define ARMA_NO_DEBUG</code>).
Alternatively, the <code>.at(n)</code>, <code>.at(i,j)</code> and <code>.at(i,j,k)</code> element access forms can be used,
which do not have bounds checks.
Either way, <b>disabling the bounds checks is not recommended</b> until your code has been thoroughly tested and debugged
-- it is better to write correct code first, and then maximise its speed.
</li>
<br>
<li>
The indices of elements are specified via the <a href="#uword">uword</a> type, which is a typedef for an <a href="#uword">unsigned integer type</a>.
When using loops to access elements, it is best to use <i>uword</i> instead of <i>int</i>.
For example: <code>for(uword&nbsp;i=0;&nbsp;i&lt;X.n_elem;&nbsp;++i)&nbsp;{&nbsp;X(i)&nbsp;=&nbsp;...&nbsp;}</code>
</li>
<br>
<li>
<b>Caveat:</b>
accessing elements via <code>[i,j]</code> and <code>[i,j,k]</code> does not work correctly in C++;
instead use <code>(i,j)</code> and <code>(i,j,k)</code> 
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 10, fill::randu);
A(9,9) = 123.0;
double x = A.at(9,9);
double y = A[99];

vec p(10, fill::randu);
p(9) = 123.0;
double z = p[9];
</pre>
</ul>
</li>                  
<br>
<li>See also:
<ul>
<li><a href="#in_range">.in_range()</a></li>
<li><a href="#element_initialisation">element initialisation</a></li>
<li><a href="#ind2sub">ind2sub()</a></li>
<li><a href="#sub2ind">sub2ind()</a></li>
<li><a href="#index_min_and_index_max_member">.index_min()&nbsp;/&nbsp;.index_max()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#memptr">.memptr()</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="#iterators_cube">iterators (cubes)</a></li>
<li><a href="#iterators_spmat">iterators (sparse matrices)</a></li>
<li><a href="#config_hpp">config.hpp</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="element_initialisation"></a>
<b>element initialisation</b>
<ul>
<li>
Set elements in <i>Mat</i>, <i>Col</i>, <i>Row</i> via initialiser lists
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec v = { 1, 2, 3 };

mat A = { {1, 3, 5},
          {2, 4, 6} };
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#element_access">element access</a></li>
<li><a href="#reshape_member">.reshape()</a></li>
<li><a href="#print">.print()</a></li>
<li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="zeros_member"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.zeros()</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.zeros( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.zeros( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.zeros( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.zeros( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Set the elements of an object to zero,
optionally first changing the size to specified dimensions
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5,10);  A.zeros();   // or:  mat A(5,10,fill::zeros);

mat B;  B.zeros(10,20);

mat C;  C.zeros( size(B) );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#zeros_standalone">zeros()</a> (standalone function)</li>
<li><a href="#ones_member">.ones()</a></li>
<li><a href="#clean">.clean()</a></li>
<li><a href="#is_zero">.is_zero()</a></li>
<li><a href="#randu_randn_member">.randu()</a></li>
<li><a href="#fill">.fill()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#reset">.reset()</a></li>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="ones_member"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.ones()</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.ones( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.ones( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.ones( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.ones( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Set all the elements of an object to one,
optionally first changing the size to specified dimensions
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5,10);  A.ones();   // or:  mat A(5,10,fill::ones);

mat B;  B.ones(10,20);

mat C;  C.ones( size(B) );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#ones_standalone">ones()</a> (standalone function)</li>
<li><a href="#eye_member">.eye()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#fill">.fill()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#randu_randn_member">.randu()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eye_member"></a>
<b>.eye()</b>
<br>
<b>.eye( n_rows, n_cols )</b>
<br>
<b>.eye( size(X) )</b>
<ul>
<li>
Member functions of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>
Set the elements along the main diagonal to one and off-diagonal elements to zero,
optionally first changing the size to specified dimensions
</li>
<br>
<li>
An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5,5);  A.eye();  // or:  mat A(5,5,fill::eye);

mat B;  B.eye(5,5);

mat C;  C.eye( size(B) );
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#ones_member">.ones()</a></li>
<li><a href="#diag">.diag()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#eye_standalone">eye()</a> (standalone function)</li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="randu_randn_member"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.randu()</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randu( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randu( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randu( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randu( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.randn()</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randn( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i> and <i>Row</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randn( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randn( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.randn( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Set all the elements to random values,
optionally first changing the size to specified dimensions
</li>
<br>
<li><i>.randu()</i> uses a uniform distribution in the [0,1] interval
</li>
<br>
<li><i>.randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance
</li>
<br>
<li>
To change the RNG seed, use <i>arma_rng::set_seed(value)</i> or <i>arma_rng::set_seed_random()</i> functions
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5,10);  A.randu();   // or:  mat A(5,10,fill::randu);

mat B;  B.randu(10,20);

mat C;  C.randu( size(B) );

arma_rng::set_seed_random();  // set the seed to a random value
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a> (standalone functions)</li>
<li><a href="#fill">.fill()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#ones_member">.ones()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="fill"></a>
<b>.fill( value )</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>field</i>
</li>
<br>
<li>Sets the elements to a specified value</li>
<br>
<li>The type of value must match the type of elements used by the container object (eg. for <i>mat</i> the type is <i>double</i>)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6);
A.fill(123.0);
</pre>
</ul>
</li>
<br>
<li>
<b>Note:</b> to explicitly set all elements to zero during object construction, use the following more compact form:
<ul>
<pre>
mat A(5, 6, fill::zeros);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#ones_member">.ones()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#randu_randn_member">.randu() &amp; .randn()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="imbue"></a>
<b>.imbue(&nbsp;</b>functor<b>&nbsp;)</b>
<br>
<b>.imbue(&nbsp;</b>lambda_function<b>&nbsp;)</b>
<br>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>
</li>
<br>
<li>
Imbue (fill) with values provided by a functor or lambda function
</li>
<br>
<li>
For matrices, filling is done column-by-column (ie. column 0 is filled, then column 1, ...)
</li>
<br>
<li>
For cubes, filling is done slice-by-slice, with each slice treated as a matrix
</li>
<br>
<li>
Examples:
<ul>
<pre>
std::mt19937 engine;  // Mersenne twister random number engine

std::uniform_real_distribution&lt;double&gt; distr(0.0, 1.0);
  
mat A(4,5);
  
A.imbue( [&amp;]() { return distr(engine); } );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#fill">.fill()</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="http://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
<li><a href="http://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="clean"></a>
<b>.clean(&nbsp;</b>threshold<b>&nbsp;)</b>
<br>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
</li>
<br>
<li>For objects with non-complex elements: each element with an absolute value &leq; <i>threshold</i> is replaced by zero</li>
<br>
<li>For objects with complex elements: for each element, each component (real and imaginary) with an absolute value &leq; <i>threshold</i> is replaced by zero</li>
<br>
<li>Can be used to sparsify a matrix, in the sense of zeroing values with small magnitudes</li>
<br>
<li><b>Caveat:</b> to explicitly convert from dense storage to sparse storage, use the <a href="#SpMat">SpMat class</a></li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A;

A.sprandu(1000, 1000, 0.01);

A(12,34) =  datum::eps;
A(56,78) = -datum::eps;

A.clean(datum::eps);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#replace">.replace()</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#is_zero">.is_zero()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#clamp">clamp()</a></li>
<li><a href="#constants">datum::eps</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="replace"></a>
<b>.replace( old_value, new_value )</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
</li>
<br>
<li>For all elements equal to <i>old_value</i>, set them to <i>new_value</i></li>
<br>
<li>The type of <i>old_value</i> and <i>new_value</i> must match the type of elements used by the container object (eg. for <i>mat</i> the type is <i>double</i>)
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>floating point numbers (<i>float</i> and <i>double</i>) are approximations due to their <a href="https://en.wikipedia.org/wiki/Floating_point">necessarily limited precision</a></li>
<li>for sparse matrices (<i>SpMat</i>), replacement is not done when <i>old_value = 0</i></li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);

A.diag().fill(datum::nan);

A.replace(datum::nan, 0);  // replace each NaN with 0
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#transform">.transform()</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#clean">.clean()</a></li>
<li><a href="#fill">.fill()</a></li>
<li><a href="#has_nan">.has_nan()</a></li>
<li><a href="#has_inf">.has_inf()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#clamp">clamp()</a></li>
<li><a href="#operators">relational operators</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="transform"></a>
<b>.transform(&nbsp;</b>functor<b>&nbsp;)</b>
<br>
<b>.transform(&nbsp;</b>lambda_function<b>&nbsp;)</b>
<br>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i>
</li>
<br>
<li>
Transform each element using a functor or lambda function
</li>
<br>
<li>
For dense matrices, transformation is done column-by-column for all elements
</li>
<br>
<li>
For sparse matrices, transformation is done column-by-column for non-zero elements
</li>
<br>
<li>
For cubes, transformation is done slice-by-slice, with each slice treated as a matrix
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::ones);

// add 123 to every element
A.transform( [](double val) { return (val + 123.0); } );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#clean">.clean()</a></li>
<li><a href="#fill">.fill()</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#operators">overloaded operators</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a> &nbsp; (exp, log, pow, sqrt, square, round, ...)</li>
<li><a href="http://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
<li><a href="http://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="for_each"></a>
<b>.for_each(&nbsp;</b>functor<b>&nbsp;)</b>
<br>
<b>.for_each(&nbsp;</b>lambda_function<b>&nbsp;)</b>
<br>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i> and <i>field</i>
</li>
<br>
<li>
For each element, pass its reference to a functor or lambda function
</li>
<br>
<li>
For dense matrices and fields, the processing is done column-by-column for all elements
</li>
<br>
<li>
For sparse matrices, the processing is done column-by-column for non-zero elements
</li>
<br>
<li>
For cubes, processing is done slice-by-slice, with each slice treated as a matrix
</li>
<br>
<li>
Examples:
<ul>
<pre>
// add 123 to each element in a dense matrix

mat A(4, 5, fill::ones);

A.for_each( [](mat::elem_type&amp; val) { val += 123.0; } );  // NOTE: the '&amp;' is crucial!


// add 123 to each non-zero element in a sparse matrix

sp_mat S; S.sprandu(1000, 2000, 0.1);

S.for_each( [](sp_mat::elem_type&amp; val) { val += 123.0; } );  // NOTE: the '&amp;' is crucial!


// set the size of all matrices in field F

field&lt;mat&gt; F(2,3);

F.for_each( [](mat&amp; X) { X.zeros(4,5); } );  // NOTE: the '&amp;' is crucial!
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#transform">.transform()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a></li>
<li><a href="#each_slice">.each_slice()</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a> &nbsp; (exp, log, pow, sqrt, square, round, ...)</li>
<li><a href="http://en.wikipedia.org/wiki/Function_object">function object</a> at Wikipedia</li>
<li><a href="http://en.wikipedia.org/wiki/C%2B%2B11#Lambda_functions_and_expressions">C++11 lambda functions</a> at Wikipedia</li>
<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="set_size"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.set_size( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.set_size( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.set_size( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i> and <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.set_size( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>Change the size of an object, without explicitly preserving data and without initialising the elements</li>
<br>
<li>
If you need to initialise the elements to zero while changing the size, use <a href="#zeros_member">.zeros()</a> instead
</li>
<br>
<li>
If you need to explicitly preserve data while changing the size, use <a href="#reshape_member">.reshape()</a> or <a href="#resize_member">.resize()</a> instead;
<br><b>caveat</b>: <i>.reshape()</i> and <i>.resize()</i> are considerably slower than <i>.set_size()</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A;  A.set_size(5,10);       // or:  mat A(5,10);

mat B;  B.set_size( size(A) );  // or:  mat B( size(A) );

vec v;  v.set_size(100);        // or:  vec v(100);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#reset">.reset()</a></li>
<li><a href="#copy_size">.copy_size()</a></li>
<li><a href="#reshape_member">.reshape()</a></li>
<li><a href="#resize_member">.resize()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="reshape_member"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.reshape( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.reshape( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.reshape( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Cube</i>, <i>SpMat</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Recreate the object according to given size specifications,
with the elements taken from the previous version of the object in a column-wise manner;
the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
</li>
<br>
<li>
The layout of the elements in the recreated object will be different to the layout in the previous version of the object
</li>
<br>
<li>
If the total number of elements in the previous version of the object is less than the specified size,
the extra elements in the recreated object are set to zero
</li>
<br>
<li>
If the total number of elements in the previous version of the object is greater than the specified size,
only a subset of the elements is taken
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>
do not use <i>.reshape()</i> if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<li>
to grow/shrink the object while preserving the elements <b>as well as</b> the layout of the elements,
use <a href="#resize_member">.resize()</a> instead
</li>
<li>
to flatten a matrix into a vector, use <a href="#vectorise">vectorise()</a> or <a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a> instead
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

A.reshape(5,4);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#resize_member">.resize()</a></li>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#copy_size">.copy_size()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#reset">.reset()</a></li>
<li><a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a></li>
<li><a href="#reshape">reshape()</a> (standalone function)</li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="resize_member"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.resize( n_elem )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Col</i>, <i>Row</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.resize( n_rows, n_cols )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i> and <i>SpMat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.resize( n_rows, n_cols, n_slices )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Cube</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.resize( size(X) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Recreate the object according to given size specifications, while preserving the elements as well as the layout of the elements
</li>
<br>
<li>
Can be used for growing or shrinking an object (ie. adding/removing rows, and/or columns, and/or slices)
</li>
<br>
<li>
<b>Caveat:</b>
do not use <i>.resize()</i> if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

A.resize(7,6);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#reshape_member">.reshape()</a></li>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#copy_size">.copy_size()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#reset">.reset()</a></li>
<li><a href="#insert">.insert_rows/cols/slices</a></li>
<li><a href="#shed">.shed_rows/cols/slices</a></li>
<li><a href="#resize">resize()</a> (standalone function)</li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="copy_size"></a>
<b>.copy_size( A )</b>
<ul>
<li>
Set the size to be the same as object <i>A</i>
</li>
<br>
<li>
Object <i>A</i> must be of the same root type as the object being modified
(eg. you can't set the size of a matrix by providing a cube)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);
mat B;
B.copy_size(A);

cout &lt;&lt; B.n_rows &lt;&lt; endl;
cout &lt;&lt; B.n_cols &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#reset">.reset()</a></li>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#reshape_member">.reshape()</a></li>
<li><a href="#resize_member">.resize()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="reset"></a>
<b>
.reset()
</b>
<ul>
<li>
Reset the size to zero (the object will have no elements)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
A.reset();
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#is_empty">.is_empty()</a></li>
<li><a href="#zeros_member">.zeros()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="submat"></a>
<b>submatrix views</b>
<ul>
<li>A collection of member functions of <i>Mat</i>, <i>Col</i> and <i>Row</i> classes that provide read/write access to submatrix views<br>
<br>
<table>
<tbody>
<tr>
<td>

<table>
<tbody>
<tr>
<td>

<li>contiguous views for matrix X:
<br>
<br>
<ul>
X.<b>col(&nbsp;</b>col_number<b>&nbsp;)</b><br>
X.<b>row(&nbsp;</b>row_number<b>&nbsp;)</b><br>
<br>
X.<b>cols(&nbsp;</b>first_col<b>,</b>&nbsp;last_col<b>&nbsp;)</b><br>
X.<b>rows(&nbsp;</b>first_row<b>,</b>&nbsp;last_row<b>&nbsp;)</b><br>
<br>
X.<b>submat(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,</b>&nbsp;last_row<b>,</b>&nbsp;last_col<b>&nbsp;)</b><br>
<br>
X<b>(&nbsp;span(</b>first_row<b>,</b>&nbsp;last_row<b>),&nbsp;span(</b>first_col<b>,</b>&nbsp;last_col<b>)&nbsp;)</b><br>
<br>
X<b>(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,&nbsp;size(</b>n_rows<b>,&nbsp;</b>n_cols<b>)&nbsp;)</b><br>
X<b>(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,&nbsp;size(</b>Y<b>)&nbsp;)</b>&nbsp;&nbsp;&nbsp;&nbsp;<i>[&nbsp;Y&nbsp;is&nbsp;a&nbsp;matrix&nbsp;]</i><br>
<br>
X<b>(</b>&nbsp;<b>span(</b>first_row<b>,</b>&nbsp;last_row<b>),</b>&nbsp;col_number&nbsp;<b>)</b><br>
X<b>(</b>&nbsp;row_number<b>,</b>&nbsp;<b>span(</b>first_col<b>,</b>&nbsp;last_col<b>)&nbsp;)</b><br>
<br>
X.<b>head_cols(&nbsp;</b>number_of_cols<b>&nbsp;)</b><br>
X.<b>head_rows(&nbsp;</b>number_of_rows<b>&nbsp;)</b><br>
<br>
X.<b>tail_cols(&nbsp;</b>number_of_cols<b>&nbsp;)</b><br>
X.<b>tail_rows(&nbsp;</b>number_of_rows<b>&nbsp;)</b><br>
<br>
X.<b>unsafe_col(&nbsp;</b>col_number<b>&nbsp;)</b>&nbsp;&nbsp;&nbsp;&nbsp;<i>[&nbsp;use&nbsp;with&nbsp;caution&nbsp;]</i><br>
</ul>
</li>

<br>

<li>
contiguous views for vector V:
<br>
<br>
<ul>
V<b>(&nbsp;span(</b>first_index<b>,</b> last_index<b>)&nbsp;)</b><br>
V.<b>subvec(&nbsp;</b>first_index<b>,</b> last_index<b>&nbsp;)</b><br>
<br>
V.<b>subvec(&nbsp;</b>first_index<b>, size(</b>W<b>)&nbsp;)</b>&nbsp;&nbsp;&nbsp;&nbsp;<i>[&nbsp;W&nbsp;is&nbsp;a&nbsp;vector&nbsp;]</i><br>
<br>
V.<b>head(&nbsp;</b>number_of_elements<b>&nbsp;)</b><br>
V.<b>tail(&nbsp;</b>number_of_elements<b>&nbsp;)</b>
</ul>
</li>


</td>
</tr>
</tbody>
</table>

</td>

<td>&nbsp;&nbsp;&nbsp;</td>
<td class="line" style="vertical-align: top;">&nbsp;</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>

<td style="vertical-align: top;">

<table>
<tbody>
<tr>
<td>

<li>non-contiguous views for matrix or vector X:
<ul>
<br>
X.<b>elem(</b>&nbsp;vector_of_indices&nbsp;<b>)</b><br>
X<b>(</b>&nbsp;vector_of_indices&nbsp;<b>)</b><br>
<br>
X.<b>cols(&nbsp;</b>vector_of_column_indices<b>&nbsp;)</b><br>
X.<b>rows(&nbsp;</b>vector_of_row_indices<b>&nbsp;)</b><br>
<br>
X.<b>submat(</b>&nbsp;vector_of_row_indices<b>,</b>&nbsp;vector_of_column_indices&nbsp;<b>)</b><br>
X<b>(</b>&nbsp;vector_of_row_indices<b>,</b>&nbsp;vector_of_column_indices&nbsp;<b>)</b><br>
<!--X.<b>elem(</b>&nbsp;vector_of_row_indices<b>,</b>&nbsp;vector_of_column_indices&nbsp;<b>)</b><br>-->
</ul>
</li>
<br>
<br>

<li>related matrix views (documented separately)
<ul>
<br>
X.<a href="#diag">diag()</a><br>
X.<a href="#each_colrow">each_row()</a><br>
X.<a href="#each_colrow">each_col()</a><br>
</ul>
</li>

</td>
</tr>
</tbody>
</table>

</td>
</tr>
</tbody>
</table>


<br>
<li>
Instances of <i>span(start,end)</i> can be replaced by <i>span::all</i> to indicate the entire range
</li>
<br>
<li>
For functions requiring one or more vector of indices,
eg. <i>X.submat(vector_of_row_indices,&nbsp;vector_of_column_indices)</i>,
each vector of indices must be of type <i><a href="#Col">uvec</a></i>
</li>
<br>
<li>
In the function <i>X.elem(vector_of_indices)</i>,
elements specified in <i>vector_of_indices</i> are accessed.
<i>X</i> is interpreted as one long vector,
with column-by-column ordering of the elements of <i>X</i>.
The <i>vector_of_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>
(eg. generated by the <a href="#find">find()</a> function).
The aggregate set of the specified elements is treated as a column vector
(ie. the output of <i>X.elem()</i> is always a column vector).
</li>
<br>
<li>
The function <i>.unsafe_col()</i> is provided for speed reasons and should be used only if you know what you are doing.
It creates a seemingly independent <i>Col</i> vector object (eg.&nbsp;<i>vec</i>),
but uses memory from the existing matrix object.
As such, the created vector is not alias safe,
and does not take into account that the underlying matrix memory could be freed
(eg. due to any operation involving a size change of the matrix).
</li>
<br>
<li>
Submatrix views of sparse matrices are only useful with Armadillo 9.600 and later versions; in earlier versions they are inefficient 
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 10, fill::zeros);

A.submat( 0,1, 2,3 )      = randu&lt;mat&gt;(3,3);
A( span(0,2), span(1,3) ) = randu&lt;mat&gt;(3,3);
A( 0,1, size(3,3) )       = randu&lt;mat&gt;(3,3);

mat B = A.submat( 0,1, 2,3 );
mat C = A( span(0,2), span(1,3) );
mat D = A( 0,1, size(3,3) );

A.col(1)        = randu&lt;mat&gt;(5,1);
A(span::all, 1) = randu&lt;mat&gt;(5,1);

mat X(5, 5, fill::randu);

// get all elements of X that are greater than 0.5
vec q = X.elem( find(X &gt; 0.5) );

// add 123 to all elements of X greater than 0.5
X.elem( find(X &gt; 0.5) ) += 123.0;

// set four specific elements of X to 1
uvec indices = { 2, 3, 6, 8 };

X.elem(indices) = ones&lt;vec&gt;(4);

// add 123 to the last 5 elements of vector a
vec a(10, fill::randu);
a.tail(5) += 123.0;

// add 123 to the first 3 elements of column 2 of X
X.col(2).head(3) += 123;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#diag">diagonal views</a></li>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a> &nbsp;&nbsp; (vector operations repeated on each column or row)</li>
<li><a href="#colptr">.colptr()</a></li>
<li><a href="#in_range">.in_range()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#join">join_rows/columns/slices</a></li>
<li><a href="#shed">shed_rows/columns/slices</a></li>
<li><a href="#insert">.insert_rows/cols/slices</a></li>
<li><a href="#size">size()</a></li>
<li><a href="#subcube">subcube views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="subcube"></a>
<b>subcube views and slices</b>
<ul>
<li>A collection of member functions of the <i>Cube</i> class that provide subcube views</li>
<br>
<table>
<tr>

<td style="vertical-align: top;">
<li>contiguous views for cube Q:
<br>
<br>
<ul>
Q.<b>row(&nbsp;</b>row_number&nbsp;<b>)</b><br>
Q.<b>rows(&nbsp;</b>first_row<b>,</b> last_row&nbsp;<b>)</b><br>
<br>
Q.<b>col(&nbsp;</b>col_number&nbsp;<b>)</b><br>
Q.<b>cols(&nbsp;</b>first_col<b>,</b> last_col&nbsp;<b>)</b><br>
<br>
Q.<b>slice(&nbsp;</b>slice_number&nbsp;<b>)</b><br>
Q.<b>slices(&nbsp;</b>first_slice<b>,</b> last_slice&nbsp;<b>)</b><br>
<br>
Q.<b>subcube(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, </b>last_row<b>,</b> last_col<b>, </b>last_slice&nbsp;<b>)</b><br>
<br>
Q<b>(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>), span(</b>first_slice<b>,</b> last_slice<b>)&nbsp;)</b><br>
<br>
Q<b>(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>n_rows<b>,</b> n_cols<b>, </b>n_slices<b>)&nbsp;)</b><br>
Q<b>(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>R<b>)&nbsp;)</b>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>[&nbsp;R&nbsp;is&nbsp;a&nbsp;cube&nbsp;]</i><br>
<br>
Q.<b>head_slices(&nbsp;</b>number_of_slices<b>&nbsp;)</b><br>
Q.<b>tail_slices(&nbsp;</b>number_of_slices<b>&nbsp;)</b><br>
<br>
Q.<b>tube(&nbsp;</b>row<b>,</b> col&nbsp;<b>)</b><br>
Q.<b>tube(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> last_row<b>,</b> last_col&nbsp;<b>)</b><br>
Q.<b>tube(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b> last_col<b>)&nbsp;)</b><br>
Q.<b>tube(&nbsp;</b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>,</b> n_cols<b>)&nbsp;)</b><br>
</ul>
</li>
</td>

<td>&nbsp;&nbsp;&nbsp;</td>
<td class="line" style="vertical-align: top;">&nbsp;</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;</td>

<td style="vertical-align: top;">
<li>non-contiguous views for cube Q:
<ul>
<br>
Q.<b>elem(</b>&nbsp;vector_of_indices&nbsp;<b>)</b><br>
Q<b>(</b>&nbsp;vector_of_indices&nbsp;<b>)</b>
<br>
<br>
Q.<b>slices(</b>&nbsp;vector_of_slice_indices&nbsp;<b>)</b><br>
</ul>
</li>
<br>
<li>related cube views (documented separately)
<ul>
<br>
Q.<a href="#each_slice">each_slice()</a><br>
</ul>
</li>
</td>

</tr>
</table>
<br>
<li>
Instances of <i>span(a,b)</i> can be replaced by:
<ul>
<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
<li><i>span(a)</i>, to indicate a particular row, column or slice</li>
</ul>
</li>
<br>
<li>
An individual slice, accessed via <i>.slice()</i>, is an instance of the <i>Mat</i> class
(a reference to a matrix is provided)
</li>
<br>
<li>
All <i>.tube()</i> forms are variants of <i>.subcube()</i>, using <i>first_slice&nbsp;=&nbsp;0</i> and <i>last_slice&nbsp;=&nbsp;Q.n_slices-1</i>
</li>
<br>
<li>
The <i>.tube(row,col)</i> form uses <i>row&nbsp;=&nbsp;first_row&nbsp;=&nbsp;last_row</i>, and <i>col&nbsp;=&nbsp;first_col&nbsp;=&nbsp;last_col</i>  
</li>
<br>
<li>
In the function <i>Q.elem(vector_of_indices)</i>,
elements specified in <i>vector_of_indices</i> are accessed.
<i>Q</i> is interpreted as one long vector,
with slice-by-slice and column-by-column ordering of the elements of <i>Q</i>.
The <i>vector_of_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>
(eg. generated by the <a href="#find">find()</a> function).
The aggregate set of the specified elements is treated as a column vector
(ie. the output of <i>Q.elem()</i> is always a column vector).
</li>
<br>
<li>
In the function <i>Q.slices(vector_of_slice_indices)</i>,
slices specified in <i>vector_of_slice_indices</i> are accessed.
The <i>vector_of_slice_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>.
</li>
<br>
<li>
Examples:
<ul>
<pre>
cube A(2, 3, 4, fill::randu);

mat  B = A.slice(1); // each slice is a matrix

A.slice(0) = randu&lt;mat&gt;(2,3);
A.slice(0)(1,2) = 99.0;

A.subcube(0,0,1,  1,1,2)             = randu&lt;cube&gt;(2,2,2);
A( span(0,1), span(0,1), span(1,2) ) = randu&lt;cube&gt;(2,2,2);
A( 0,0,1, size(2,2,2) )              = randu&lt;cube&gt;(2,2,2);

// add 123 to all elements of A greater than 0.5
A.elem( find(A &gt; 0.5) ) += 123.0;

cube C = A.head_slices(2);  // get first two slices

A.head_slices(2) += 123.0;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#in_range">.in_range()</a></li>
<li><a href="#each_slice">.each_slice()</a></li>
<li><a href="#join_slices">join_slices()</a></li>
<li><a href="#shed">shed_slices()</a></li>
<li><a href="#insert">insert_slices()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="#submat">submatrix views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="subfield"></a>
<b>subfield views</b>
<ul>
<li>A collection of member functions of the <i>field</i> class that provide subfield views<br>
<br>
<li>For a 2D field <i>F</i>, the subfields are accessed as:</li>
<br>
<ul>
F.<b>row(&nbsp;</b>row_number&nbsp;<b>)</b><br>
F.<b>col(&nbsp;</b>col_number&nbsp;<b>)</b><br>
<br>
F.<b>rows(&nbsp;</b>first_row<b>,</b> last_row&nbsp;<b>)</b><br>
F.<b>cols(&nbsp;</b>first_col<b>,</b> last_col&nbsp;<b>)</b><br>
<br>
F.<b>subfield(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,</b> last_row<b>,</b>&nbsp;last_col <b>)</b><br>
<br>
F<b>(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b>&nbsp;last_col<b>) )</b><br>
<br>
F<b>(&nbsp;</b>first_row<b>,</b> first_col<b>, size(</b>G<b>)&nbsp;)</b> &nbsp;&nbsp;&nbsp;<i>[&nbsp;G&nbsp;is&nbsp;a&nbsp;2D&nbsp;field&nbsp;]</i><br>
F<b>(&nbsp;</b>first_row<b>,</b> first_col<b>, size(</b>n_rows<b>, </b>n_cols<b>)&nbsp;)</b><br>
</ul>
<br>
<li>For a 3D field <i>F</i>, the subfields are accessed as:</li>
<br>
<ul>
F.<b>slice(&nbsp;</b>slice_number&nbsp;<b>)</b><br>
<br>
F.<b>slices(&nbsp;</b>first_slice<b>,</b> last_slice&nbsp;<b>)</b><br>
<br>
F.<b>subfield(&nbsp;</b>first_row<b>,</b>&nbsp;first_col<b>,</b>&nbsp;first_slice<b>,</b> last_row<b>,</b>&nbsp;last_col<b>,</b>&nbsp;last_slice <b>)</b><br>
<br>
F<b>(&nbsp;span(</b>first_row<b>,</b> last_row<b>), span(</b>first_col<b>,</b>&nbsp;last_col<b>), span(</b>first_slice<b>,</b>&nbsp;last_slice<b>) )</b><br>
<br>
F<b>(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>G<b>)&nbsp;)</b> &nbsp;&nbsp;&nbsp;<i>[&nbsp;G&nbsp;is&nbsp;a&nbsp;3D&nbsp;field&nbsp;]</i><br>
F<b>(&nbsp;</b>first_row<b>,</b> first_col<b>,</b> first_slice<b>, size(</b>n_rows<b>, </b>n_cols<b>, </b>n_slices<b>)&nbsp;)</b><br>
</ul>
</li>
<br>
<li>
Instances of <i>span(a,b)</i> can be replaced by:
<ul>
<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
<li><i>span(a)</i>, to indicate a particular row or column</li>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#in_range">.in_range()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="diag"></a>
<b>.diag()</b>
<br><b>.diag( k )</b>
<ul>
<li>
Member function of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>
Read/write access to a diagonal in a matrix
</li>
<br>
<li>The argument <i>k</i> is optional; by default the main diagonal is accessed (<i>k=0</i>)</li>
<br>
<li>For <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is accessed (top-right corner)</li>
<br>
<li>For <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is accessed (bottom-left corner)</li>
<br>
<li>The diagonal is interpreted as a column vector within expressions</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);

vec a = X.diag();
vec b = X.diag(1);
vec c = X.diag(-2);

X.diag() = randu&lt;vec&gt;(5);
X.diag() += 6;
X.diag().ones();
</pre>
</ul>
</li>
<br>
<li>
<b>NOTE:</b> handling of sparse matrix diagonals has changed slightly between Armadillo 7.x and 8.x;
to copy sparse diagonal to dense vector, use:
<ul>
<pre>
sp_mat S = sprandu&lt;sp_mat&gt;(10,10,0.1);

vec v(S.diag());  // copy sparse diagonal to dense vector
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eye_member">.eye()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a></li>
<li><a href="#trace">trace()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="each_colrow"></a>
<b>.each_col()</b>
<br>
<b>.each_row()</b>
<br>
<br>
<b>.each_col(</b>&nbsp;vector_of_indices&nbsp;<b>)</b>
<br>
<b>.each_row(</b>&nbsp;vector_of_indices&nbsp;<b>)</b>
<br>
<br>
<b>.each_col(</b> lambda_function <b>)</b>&nbsp;&nbsp;&nbsp;
<br>
<b>.each_row(</b> lambda_function <b>)</b>&nbsp;&nbsp;&nbsp;
<ul>
<li>
Member functions of <i>Mat</i>
</li>
<br>
<li>
Apply a vector operation to each column or row of a matrix
</li>
<br>
<li>
Similar to "broadcasting" in Matlab/Octave
</li>
<br>
<li>
Supported operations for <i>.each_col()&nbsp;/&nbsp;.each_row()</i> and <i>.each_col(vector_of_indices)&nbsp;/&nbsp;.each_row(vector_of_indices)</i> forms:
<br>
<br>
<ul>
<table>
<tr><td><code><b>+</b></code></td><td>&nbsp;</td><td>addition</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>+=</b></code></td><td>&nbsp;</td><td>in-place addition</td></tr>
<tr><td><code><b>-</b></code></td><td>&nbsp;</td><td>subtraction</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>-=</b></code></td><td>&nbsp;</td><td>in-place subtraction</td></tr>
<tr><td><code><b>%</b></code></td><td>&nbsp;</td><td>element-wise multiplication</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>%=</b></code></td><td>&nbsp;</td><td>in-place element-wise multiplication</td></tr>
<tr><td><code><b>/</b></code></td><td>&nbsp;</td><td>element-wise division</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>/=</b></code></td><td>&nbsp;</td><td>in-place element-wise division</td></tr>
<tr><td><code><b>=</b></code></td><td>&nbsp;</td><td>assignment (copy)</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
</table>
</ul>
</li>
<br>
<li>The argument <i>vector_of_indices</i> is optional; by default all columns or rows are used</li>
<br>
<li>
If the argument <i>vector_of_indices</i> is specified, it must evaluate to a vector of type <i><a href="#Col">uvec</a></i>;
the vector contains a list of indices of the columns or rows to be used
</li>
<br>
<li>
If the <i>lambda_function</i> is specified,
the function must accept a reference to a <a href="#Col">Col</a> or <a href="#Row">Row</a> object with the same element type as the underlying matrix
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(6, 5, fill::ones);
vec v = linspace&lt;vec&gt;(10,15,6);

X.each_col() += v;         // in-place addition of v to each column vector of X

mat Y = X.each_col() + v;  // generate Y by adding v to each column vector of X

// subtract v from columns 0 through to 3 in X
X.cols(0,3).each_col() -= v;


uvec indices(2);
indices(0) = 2;
indices(1) = 4;

X.each_col(indices) = v;   // copy v to columns 2 and 4 in X


X.each_col( [](vec&amp; a){ a.print(); } );     // lambda function with non-const vector

const mat&amp; XX = X;
XX.each_col( [](const vec&amp; b){ b.print(); } );  // lambda function with const vector
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#operators">math &amp; relational operators</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#diag">diagonal views</a></li>
<li><a href="#repmat">repmat()</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#each_slice">.each_slice()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="each_slice"></a>
<table>
<tr><td><b>.each_slice()</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 1)</td></tr>
<tr><td><b>.each_slice(</b>&nbsp;vector_of_indices&nbsp;<b>)</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 2)</td></tr>
<tr><td><b>.each_slice(</b>&nbsp;lambda_function&nbsp;<b>)</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 3)</td></tr>
<tr><td><b>.each_slice(</b>&nbsp;lambda_function, use_mp&nbsp;<b>)</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 4)</td></tr>
</table>
<ul>
<li>
Member function of <i>Cube</i>
</li>
<br>
<li>
Apply a matrix operation to each slice of a cube, with each slice treated as a matrix
</li>
<br>
<li>
Similar to "broadcasting" in Matlab/Octave
</li>
<br>
<li>
Supported operations for form 1:
<br>
<br>
<ul>
<table>
<tr><td><code><b>+</b></code></td><td>&nbsp;</td><td>addition</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>+=</b></code></td><td>&nbsp;</td><td>in-place addition</td></tr>
<tr><td><code><b>-</b></code></td><td>&nbsp;</td><td>subtraction</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>-=</b></code></td><td>&nbsp;</td><td>in-place subtraction</td></tr>
<tr><td><code><b>%</b></code></td><td>&nbsp;</td><td>element-wise multiplication</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>%=</b></code></td><td>&nbsp;</td><td>in-place element-wise multiplication</td></tr>
<tr><td><code><b>/</b></code></td><td>&nbsp;</td><td>element-wise division</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>/=</b></code></td><td>&nbsp;</td><td>in-place element-wise division</td></tr>
<tr><td><code><b>*</b></code></td><td>&nbsp;</td><td>matrix multiplication</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td><code><b>*=</b></code></td><td>&nbsp;</td><td>in-place matrix multiplication</td></tr>
<tr><td><code><b>=</b></code></td><td>&nbsp;</td><td>assignment (copy)</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
</table>
</ul>
</li>
<br>
<li>
For form 2:
<ul>
<li>the argument <i>vector_of_indices</i> contains a list of indices of the slices to be used; it must evaluate to a vector of type <i><a href="#Col">uvec</a></i></li>
<li>arithmetic operations as per form 1 are supported, except for <code><b>*</b></code> and <code><b>*=</b></code> (ie. matrix multiplication)</li>
</ul>
</li>
<br>
<li>
For form 3:
<ul>
<li>apply the given <i>lambda_function</i> to each slice; the function must accept a reference to a <a href="#Mat">Mat</a> object with the same element type as the underlying cube</li>
</ul>
</li>
<br>
<li>
For form 4:
<ul>
<li>apply the given <i>lambda_function</i> to each slice, as per form 3</li>
<li>the argument <i>use_mp</i> is a bool which enables the use of OpenMP for multi-threaded execution of <i>lambda_function</i> on multiple slices at the same time</li>
<li>the order of processing the slices is not deterministic (eg. slice&nbsp;2 can be processed before slice&nbsp;1)</li>
<li><i>lambda_function</i> must be thread-safe, ie. it must not write to variables outside of its scope
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
cube C(4, 5, 6, fill::randu);

mat M = repmat(linspace&lt;vec&gt;(1,4,4), 1, 5);

C.each_slice() += M;          // in-place addition of M to each slice of C

cube D = C.each_slice() + M;  // generate D by adding M to each slice of C


uvec indices(2);
indices(0) = 2;
indices(1) = 4;

C.each_slice(indices) = M;    // copy M to slices 2 and 4 in C


C.each_slice( [](mat&amp; X){ X.print(); } );     // lambda function with non-const matrix

const cube&amp; CC = C;
CC.each_slice( [](const mat&amp; X){ X.print(); } );  // lambda function with const matrix
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#operators">math &amp; relational operators</a></li>
<li><a href="#subcube">subcube views</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a> &nbsp;</li>
<li><a href="http://www.cprogramming.com/c++11/c++11-lambda-closures.html">lambda function</a> at cprogramming.com</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="set_imag"></a>
<b>.set_imag( X )</b>
<br>
<b>.set_real( X )</b>
<br>  
<ul>
<li>
Set the imaginary/real part of an object
</li>
<br>
<li>
<i>X</i> must have the same size as the recipient object
</li>
<br>
<li>
Examples:
<ul>
<pre>
   mat A(4, 5, fill::randu);
   mat B(4, 5, fill::randu);

cx_mat C(4, 5, fill::zeros);

C.set_real(A);
C.set_imag(B);
</pre>
</ul>
</li>
<br>
<li>
<b>Caveat:</b>
to directly construct a complex matrix out of two real matrices,
the following code is faster:
<ul>
<pre>
   mat A(4, 5, fill::randu);
   mat B(4, 5, fill::randu);

cx_mat C = cx_mat(A,B);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#constructors_mat">matrix constructors</a></li>
<li><a href="#constructors_cube">cube constructors</a></li>
<li><a href="#imag_real">imag()&nbsp;/&nbsp;real()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="insert"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>.insert_rows(&nbsp;</b>row_number, X<b>&nbsp;)</b>
      <br>
      <b>.insert_rows(&nbsp;</b>row_number, number_of_rows&nbsp;<b>)</b>
      <br>
      <b>.insert_rows(&nbsp;</b>row_number, number_of_rows, set_to_zero&nbsp;<b>)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Col</i> and <i>Cube</i>)
      </td>
    </tr>
    <tr>
    <td>&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.insert_cols(&nbsp;</b>col_number<b>,</b> X<b>&nbsp;)</b>
      <br>
      <b>.insert_cols(&nbsp;</b>col_number<b>,</b> number_of_cols&nbsp;<b>)</b>
      <br>
      <b>.insert_cols(&nbsp;</b>col_number<b>,</b> number_of_cols<b>,</b> set_to_zero&nbsp;<b>)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member functions of <i>Mat</i>, <i>Row</i> and <i>Cube</i>)
      </td>
    </tr>
    <tr>
    <td>&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.insert_slices(&nbsp;</b>slice_number<b>,</b> X<b>&nbsp;)</b>
      <br>
      <b>.insert_slices(&nbsp;</b>slice_number<b>,</b> number_of_slices&nbsp;<b>)</b>
      <br>
      <b>.insert_slices(&nbsp;</b>slice_number<b>,</b> number_of_slices<b>,</b> set_to_zero&nbsp;<b>)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member functions of <i>Cube</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Functions with the <i>X</i> argument: insert a copy of <i>X</i> at the specified row/column/slice
<ul>
<li>if inserting rows, <i>X</i> must have the same number of columns (and slices) as the recipient object</li>
<li>if inserting columns, <i>X</i> must have the same number of rows (and slices) as the recipient object</li>
<li>if inserting slices, <i>X</i> must have the same number of rows and columns as the recipient object (ie. all slices must have the same size)</li>
</ul>
</li>
<br>
<li>
Functions with the <i>number_of_...</i> argument:
<ul>
<li>expand the object by creating new rows/columns/slices</li>
<li>by default, the new rows/columns/slices are set to zero</li>
<li>if <i>set_to_zero</i> is <i>false</i>, the memory used by the new rows/columns/slices will not be initialised</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 10, fill::randu);
mat B(5,  2, fill::ones );

// at column 2, insert a copy of B;
// A will now have 12 columns
A.insert_cols(2, B);

// at column 1, insert 5 zeroed columns;
// B will now have 7 columns
B.insert_cols(1, 5);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#shed">shed_rows/columns/slices</a></li>
<li><a href="#join">join_rows/columns/slices</a></li>
<li><a href="#resize_member">.resize()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="shed"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>.shed_row(&nbsp;</b>row_number<b>&nbsp;)</b>
      <br>
      <b>.shed_rows(&nbsp;</b>first_row, last_row<b>&nbsp;)</b>
      <br>
      <b>.shed_rows(&nbsp;</b>vector_of_indices<b>&nbsp;)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">
      (member function of <i>Mat</i>, <i>Col</i>, <i>SpMat</i>, <i>Cube</i>)
      <br>
      (member function of <i>Mat</i>, <i>Col</i>, <i>SpMat</i>, <i>Cube</i>)
      <br>
      (member function of <i>Mat</i>, <i>Col</i>)
      </td>
    </tr>
    <tr>
    <td>&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.shed_col(&nbsp;</b>column_number<b>&nbsp;)</b>
      <br>
      <b>.shed_cols(&nbsp;</b>first_column, last_column<b>&nbsp;)</b>
      <br>
      <b>.shed_cols(&nbsp;</b>vector_of_indices<b>&nbsp;)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">
      (member function of <i>Mat</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
      <br>
      (member function of <i>Mat</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i>)
      <br>
      (member function of <i>Mat</i>, <i>Row</i>)
      </td>
    </tr>
    <tr>
    <td>&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.shed_slice(&nbsp;</b>slice_number<b>&nbsp;)</b>
      <br>
      <b>.shed_slices(&nbsp;</b>first_slice, last_slice<b>&nbsp;)</b>
      <br>
      <b>.shed_slices(&nbsp;</b>vector_of_indices<b>&nbsp;)</b>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member functions of <i>Cube</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>
Functions with single scalar argument: remove the specified row/column/slice
</li>
<br>
<li>
Functions with two scalar arguments: remove the specified range of rows/columns/slices
</li>
<br>
<li>
The <i>vector_of_indices</i> must evaluate to a vector of type <a href="#Col">uvec</a>; it contains the indices of rows/columns/slices to remove
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 10, fill::randu);
mat B(5, 10, fill::randu);

A.shed_row(2);
A.shed_cols(2,4);

uvec indices = {4, 6, 8};
B.shed_cols(indices);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#insert">insert_rows/columns/slices</a></li>
<li><a href="#join">join_rows/columns/slices</a></li>
<li><a href="#resize_member">.resize()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
<li><a href="http://thesaurus.com/browse/shed"><i>shed</i> in thesaurus.com</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="swap_rows"></a>
<b>
.swap_rows( row1, row2 )
<br>.swap_cols( col1, col2 )
</b>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>SpMat</i>
</li>
<br>
<li>
Swap the contents of specified rows or columns
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);
X.swap_rows(0,4);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#flip">fliplr() &amp; flipud()</a></li>
<li><a href="#swap">.swap()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="swap"></a>
<b>.swap( X )</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>
</li>
<br>
<li>
Swap contents with object <i>X</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::zeros);
mat B(6, 7, fill::ones );

A.swap(B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#swap_rows">.swap_rows() &amp; .swap_cols()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="memptr"></a>
<b>.memptr()</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i> 
</li>
<br>
<li>
Obtain a raw pointer to the memory used for storing elements
</li>
<br>
<li>
The function can be used for interfacing with libraries such as <a href="http://www.fftw.org/">FFTW</a>
</li>
<br>
<li>
Data for matrices is stored in a column-by-column order
</li>
<br>
<li>
Data for cubes is stored in a slice-by-slice (matrix-by-matrix) order
</li>
<br>
<li>
<b>Caveat:</b> the pointer becomes invalid after any operation involving a size change or aliasing
</li>
<br>
<li>
<b>Caveat:</b> this function is not recommended for use unless you know what you are doing!
</li>
<br>
<li>
Examples:
<ul>
<pre>
      mat A(5, 5, fill::randu);
const mat B(5, 5, fill::randu);

      double* A_mem = A.memptr();
const double* B_mem = B.memptr();
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#colptr">.colptr()</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="#iterators_cube">iterators (cubes)</a></li>
<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
<li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="colptr"></a>
<b>.colptr( col_number )</b>
<ul>
<li>
Member function of <i>Mat</i>
</li>
<br>
<li>
Obtain a raw pointer to the memory used by the specified column
</li>
<br>
<li>
<b>Caveat:</b> the pointer becomes invalid after any operation involving a size change or aliasing
</li>
<br>
<li>
<b>Caveat:</b> this function is not recommended for use unless you know what you are doing
-- it is safer to use <a href="#submat">submatrix views</a> instead
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double* mem = A.colptr(2);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#memptr">.memptr()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="iterators_mat"></a>
<b>iterators (dense matrices &amp; vectors)</b>
<ul>
<li>
Iterators and associated member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>
</li>
<br>
<li>
Iterators for dense matrices and vectors traverse over all elements within the specified range
</li>
<br>
<li>
Member functions:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin_col(&nbsp;col_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element of the specified column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end_col(&nbsp;col_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element of the specified column
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin_row(&nbsp;row_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element of the specified row
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end_row(&nbsp;row_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element of the specified row
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
Iterator types:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::iterator</b>
      <br>
      <b>vec::iterator</b>
      <br>
      <b>rowvec::iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read/write access to elements (which are stored column by column)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::const_iterator</b>
      <br>
      <b>vec::const_iterator</b>
      <br>
      <b>rowvec::const_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read-only access to elements (which are stored column by column)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::col_iterator</b>
      <br>
      <b>vec::col_iterator</b>
      <br>
      <b>rowvec::col_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read/write access to the elements of specified columns
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::const_col_iterator</b>
      <br>
      <b>vec::const_col_iterator</b>
      <br>
      <b>rowvec::const_col_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read-only access to the elements of specified columns
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read/write access to the elements of specified rows
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>mat::const_row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read-only access to the elements of specified rows
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>vec::row_iterator</b>
      <br>
      <b>rowvec::row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read/write access to the elements of specified rows
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>vec::const_row_iterator</b>
      <br>
      <b>rowvec::const_row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterators, for read-only access to the elements of specified rows
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 6, fill::randu);

mat::iterator it     = X.begin();
mat::iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout &lt;&lt; (*it) &lt;&lt; endl;
  }

mat::col_iterator col_it     = X.begin_col(1);  // start of column 1
mat::col_iterator col_it_end = X.end_col(3);    //   end of column 3

for(; col_it != col_it_end; ++col_it)
  {
  cout &lt;&lt; (*col_it) &lt;&lt; endl;
  (*col_it) = 123.0;
  }
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#Mat">Mat class</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#memptr">.memptr()</a></li>
<li><a href="#colptr">.colptr()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#iterators_submat">iterators (submatrices)</a></li>
<li><a href="#iterators_cube">iterators (cubes)</a></li>
<li><a href="#iterators_spmat">iterators (sparse matrices)</a></li>
<li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="iterators_cube"></a>
<b>iterators (cubes)</b>
<ul>
<li>
Iterators and associated member functions of <i>Cube</i>
</li>
<br>
<li>
Iterators for cubes traverse over all elements within the specified range
</li>
<br>
<li>
Member functions:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin_slice( slice_number )</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element of the specified slice
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end_slice( slice_number )</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element of the specified slice
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
Iterator types:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>cube::iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterator, for read/write access to elements;
        the elements are ordered slice by slice;
        the elements within each slice are ordered column by column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>cube::const_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterator, for read-only access to elements
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>cube::slice_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterator, for read/write access to the elements of a particular slice;
        the elements are ordered column by column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>cube::const_slice_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        random access iterator, for read-only access to the elements of a particular slice
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
cube X(2, 3, 4, fill::randu);

cube::iterator it     = X.begin();
cube::iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout &lt;&lt; (*it) &lt;&lt; endl;
  }

cube::slice_iterator s_it     = X.begin_slice(1);  // start of slice 1
cube::slice_iterator s_it_end = X.end_slice(2);    // end of slice 2

for(; s_it != s_it_end; ++s_it)
  {
  cout &lt;&lt; (*s_it) &lt;&lt; endl;
  (*s_it) = 123.0;
  }
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#Cube">Cube class</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#memptr">.memptr()</a></li>
<li><a href="#subcube">subcube views</a></li>
<li><a href="#iterators_submat">iterators (subcubes)</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="iterators_spmat"></a>
<b>iterators (sparse matrices)</b>
<ul>
<li>
Iterators and associated member functions of <i>SpMat</i>
</li>
<br>
<li>
Iterators for sparse matrices traverse over non-zero elements within the specified range
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>
to modify the non-zero elements in a safer manner,
use <a href="#transform">.transform()</a> or <a href="#for_each">.for_each()</a> instead of iterators;
<br>
writing a zero value into a sparse matrix through an iterator will invalidate all current iterators associated with the sparse matrix</li>
<li>row iterators for sparse matrices are only useful with Armadillo 8.500 and later versions; in earlier versions they are inefficient
</ul>
</li>
<br>
<li>
Member functions:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin_col(&nbsp;col_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element of the specified column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end_col(&nbsp;col_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element of the specified column
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.begin_row(&nbsp;row_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the first element of the specified row
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>.end_row(&nbsp;row_number&nbsp;)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        iterator referring to the <i>past-the-end</i> element of the specified row
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
Iterator types:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read/write access to elements (which are stored column by column)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::const_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read-only access to elements (which are stored column by column)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::col_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read/write access to the elements of a specific column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::const_col_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read-only access to the elements of a specific column
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read/write access to the elements of a specific row
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top; text-align: right;">
      <b>sp_mat::const_row_iterator</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        bidirectional iterator, for read-only access to the elements of a specific row
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      &nbsp;
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
The iterators have <i>.row()</i> and <i>.col()</i> functions which return the row and column of the current element;
the returned values are of type <a href="#uword">uword</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat X = sprandu&lt;sp_mat&gt;(1000, 2000, 0.1);

sp_mat::const_iterator it     = X.begin();
sp_mat::const_iterator it_end = X.end();

for(; it != it_end; ++it)
  {
  cout &lt;&lt; "val: " &lt;&lt; (*it)    &lt;&lt; endl;
  cout &lt;&lt; "row: " &lt;&lt; it.row() &lt;&lt; endl;
  cout &lt;&lt; "col: " &lt;&lt; it.col() &lt;&lt; endl;
  }
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#SpMat">SpMat class</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="http://cplusplus.com/reference/std/iterator/">iterator at cplusplus.com</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="iterators_submat"></a>
<b>iterators (dense submatrices &amp; subcubes)</b>
<ul>
<li>
iterators for dense <a href="#submat">submatrix</a> and <a href="#subcube">subcube</a> views,
allowing range-based for loops
</li>
<br>
<li>
<b>Caveat:</b>
These iterators are intended <b>only</b> to be used with range-based for loops. Any other use is not supported.
For example, the direct use of the <i>begin()</i> and <i>end()</i> functions, as well as the underlying iterators types is not supported.
The implementation of submatrices and subcubes uses short-lived temporary objects that are subject to automatic deletion, and as such are error-prone to handle manually.
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(100, 200, fill::randu);

for( double&amp; val : X(span(40,60), span(50,100)) )
  {
  cout &lt;&lt; val &lt;&lt; endl;
  val = 123.0;
  }
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#for_each">.for_each()</a></li>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="#iterators_cube">iterators (cubes)</a></li>
<li><a href="http://en.cppreference.com/w/cpp/language/range-for">range-based for</a> (cppreference.com)</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="compat_container_fns"></a>
<b>compatibility container functions</b>
<ul>
<li>Member functions to mimic the functionality of containers in the C++ standard library:<br>
<br>

<table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>.front()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        access the first element in a vector
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.back()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        access the last element in a vector
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.clear()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        causes an object to have no elements
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.empty()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        returns <i>true</i> if the object has no elements; returns <i>false</i> if the object has one or more elements
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>.size()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
        returns the total number of elements
      </td>
    </tr>
  </tbody>
</table>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
cout &lt;&lt; A.size() &lt;&lt; endl;

A.clear();
cout &lt;&lt; A.empty() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#iterators_mat">iterators (dense matrices)</a></li>
<li><a href="#iterators_cube">iterators (cubes)</a></li>
<li><a href="#iterators_spmat">iterators (sparse matrices)</a></li>
<li><a href="#attributes">matrix and vector attributes</a></li>
<li><a href="#is_empty">.is_empty()</a></li>
<li><a href="#reset">.reset()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="as_col_row"></a>
<b>
.as_col()
<br>.as_row()
</b>
<ul>
<li>
Member functions of any matrix expression
</li>
<br>
<li>
<i>.as_col()</i>: return a flattened version of the matrix as a column vector; flattening is done by concatenating all columns
</li>
<br>
<li>
<i>.as_row()</i>: return a flattened version of the matrix as a row vector; flattening is done by concatenating all rows
</li>
<br>
<li>
<b>Caveat:</b> concatenating columns is faster than concatenating rows
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4, 5, fill::randu);
vec v = X.as_col();
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#reshape_member">.reshape()</a></li>
<li><a href="#t_st_members">.t()&nbsp;/&nbsp;.st()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="t_st_members"></a>
<b>
.t()
<br>.st()
</b>
<ul>
<li>
Member functions of any matrix or vector expression
</li>
<br>
<li>
For real (non-complex) matrix:
<ul>
<li><i>.t()</i> provides a transposed copy of the matrix</li>
<li><i>.st()</i> not applicable</li>
</ul>
</li>
<br>
<li>
For complex matrix:
<ul>
<li><i>.t()</i> provides a Hermitian transpose (ie. the conjugate of the elements is taken during the transpose)</li>
<li><i>.st()</i> provides a transposed copy without taking the conjugate of the elements</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B = A.t();
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#trans">trans()</a></li>
<li><a href="#flip">fliplr() &amp; flipud()</a></li>
<li><a href="#reverse">reverse()</a></li>
<li><a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="i_member"></a>
<b>.i()</b>
<ul>
<li>
Member function of any matrix expression
</li>
<br>
<li>
Provides an inverse of the matrix expression
</li>
<br>
<li>
If the matrix expression is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>
If the matrix expression appears to be singular, the output matrix is reset and a <i>std::runtime_error</i> exception is thrown
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>
if matrix <i>A</i> is know to be symmetric positive definite, it is faster to use <a href="#inv_sympd">inv_sympd()</a> instead 
</li>
<li>
to solve a system of linear equations, such as <i>Z&nbsp;=&nbsp;inv(X)*Y</i>,
using <a href="#solve">solve()</a> can be faster and/or more accurate
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 4, fill::randu);

mat X = A.i();

mat Y = (A+A).i();
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#inv">inv()</a></li>
<li><a href="#rcond">rcond()</a></li>
<li><a href="#pinv">pinv()</a></li>
<li><a href="#solve">solve()</a></li>
<li><a href="#spsolve">spsolve()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="min_and_max_member"></a>
<b>.min()</b>
<br><b>.max()</b>
<ul>
<li>
Return the extremum value of any matrix or cube expression
</li>
<br>
<li>
For objects with complex numbers, absolute values are used for comparison
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double max_val = A.max();
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#index_min_and_index_max_member">.index_min() &amp; .index_max()</a></li>
<li><a href="#min_and_max">min() &amp; max()</a> (standalone functions with extended functionality)</li>
<li><a href="#clamp">clamp()</a>
<li><a href="#running_stat">running_stat</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="index_min_and_index_max_member"></a>
<b>.index_min()</b>
<br><b>.index_max()</b>
<ul>
<li>
Return the linear index of the extremum value of any matrix or cube expression
</li>
<br>
<li>
For objects with complex numbers, absolute values are used for comparison
</li>
<br>
<li>
The returned index is of type <a href="#uword">uword</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

uword i = A.index_max();

double max_val = A(i);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#min_and_max_member">.min() &amp; .max()</a></li>
<li><a href="#index_min_and_index_max_standalone">index_min() &amp; index_max()</a> (standalone functions with extended functionality)</li>
<li><a href="#ind2sub">ind2sub()</a></li>
<li><a href="#sort_index">sort_index()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#element_access">element access</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eval_member"></a>
<b>.eval()</b>
<br>
<ul>
<li>
Member function of any matrix or vector expression
</li>
<br>
<li>
Explicitly forces the evaluation of a delayed expression and outputs a matrix
</li>
<br>
<li>
This function should be used sparingly and only in cases where it is absolutely necessary;
indiscriminate use can cause performance degradations
</li>
<br>
<li>
Examples:
<ul>
<pre>
cx_mat A( randu&lt;mat&gt;(4,4), randu&lt;mat&gt;(4,4) );

real(A).eval().save("A_real.dat", raw_ascii);
imag(A).eval().save("A_imag.dat", raw_ascii);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#Mat">Mat class</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="in_range"></a>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> i <b>)</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range( span(</b>start<b>,</b> end<b>) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col <b>)</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> <font size=-1><b>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>)</b></font> <b>)</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> row<b>,</b> col<b>,</b> slice <b>)</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> <font size=-1><b>span(</b>start_row<b>,</b> end_row<b>), span(</b>start_col<b>,</b> end_col<b>), span(</b>start_slice<b>,</b> end_slice<b>)</b></font> <b>)</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, size(</b>X<b>) )</b> &nbsp;&nbsp;<i>(X is a matrix or field)</i></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, size(</b>n_rows<b>,</b> n_cols<b>) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>field</i>)
      </td>
    </tr>
    <tr>
      <td>
      &nbsp;
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, </b> first_slice<b>, size(</b>Q<b>) )</b> &nbsp;&nbsp;<i>(Q is a cube or field)</i></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><b>.in_range(</b> first_row<b>,</b> first_col<b>, </b> first_slice<b>, size(</b>n_rows<b>,</b> n_cols<b></b> n_slices<b>) )</b></td>
      <td style="vertical-align: top;"><br>
      </td>
      <td>&nbsp;</td>
      <td style="vertical-align: top;">(member of <i>Cube</i> and <i>field</i>)
      </td>
    </tr>
  </tbody>
</table>
<ul>
<li>Returns <i>true</i> if the given location or span is currently valid
</li>
<br>
<li>Returns <i>false</i> if the object is empty, the location is out of bounds, or the span is out of bounds
</li>
<br>
<li>
Instances of <i>span(a,b)</i> can be replaced by:
<ul>
<li><i>span()</i> or <i>span::all</i>, to indicate the entire range</li>
<li><i>span(a)</i>, to indicate a particular row, column or slice</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

cout &lt;&lt; A.in_range(0,0) &lt;&lt; endl;  // true
cout &lt;&lt; A.in_range(3,4) &lt;&lt; endl;  // true
cout &lt;&lt; A.in_range(4,5) &lt;&lt; endl;  // false
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#element_access">element access</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
<li><a href="#subfield">subfield views</a></li>
<li><a href="#set_size">.set_size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_empty"></a>
<b>.is_empty()</b>
<ul>
<li>Returns <i>true</i> if the object has no elements
</li>
<br>
<li>Returns <i>false</i> if the object has one or more elements
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
cout &lt;&lt; A.is_empty() &lt;&lt; endl;

A.reset();
cout &lt;&lt; A.is_empty() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_square">.is_square()</a></li>
<li><a href="#is_vec">.is_vec()</a></li>
<li><a href="#is_finite">.is_finite()</a></li>
<li><a href="#reset">.reset()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_vec"></a>
<b>.is_vec()</b>
<br><b>.is_colvec()</b>
<br><b>.is_rowvec()</b>
<ul>
<li>
Member functions of <i>Mat</i> and <i>SpMat</i>
</li>
<br>

<li>.is_vec():
<ul>
<li>returns <i>true</i> if the matrix can be interpreted as a vector (either column or row vector)
</li>
<li>returns <i>false</i> if the matrix does not have exactly one column or one row
</li>
</ul>
</li>
<br>

<li>.is_colvec():
<ul>
<li>returns <i>true</i> if the matrix can be interpreted as a column vector
</li>
<li>returns <i>false</i> if the matrix does not have exactly one column
</li>
</ul>
</li>
<br>

<li>.is_rowvec():
<ul>
<li>returns <i>true</i> if the matrix can be interpreted as a row vector
</li>
<li>returns <i>false</i> if the matrix does not have exactly one row
</li>
</ul>
</li>
<br>

<li><b>Caveat:</b> do not assume that the vector has elements if these functions return <i>true</i>; it is possible to have an empty vector (eg. 0x1)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(1, 5, fill::randu);
mat B(5, 1, fill::randu);
mat C(5, 5, fill::randu);

cout &lt;&lt; A.is_vec() &lt;&lt; endl;
cout &lt;&lt; B.is_vec() &lt;&lt; endl;
cout &lt;&lt; C.is_vec() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_empty">.is_empty()</a></li>
<li><a href="#is_square">.is_square()</a></li>
<li><a href="#is_finite">.is_finite()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_sorted"></a>
<b>.is_sorted()</b>
<br><b>.is_sorted( sort_direction )</b>
<br><b>.is_sorted( sort_direction, dim )</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Row</i> and <i>Col</i>
</li>
<br>
<li>
If the object is a vector, return a <i>bool</i> indicating whether the elements are sorted
</li>
<br>
<li>
If the object is a matrix, return a <i>bool</i> indicating whether the elements are sorted in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is one of:
<ul>
<table>
<tbody>
<tr><td><code>"ascend"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>elements are ascending; consecutive elements can be equal; this is the <b>default operation</b></td></tr>
<tr><td><code>"descend"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>elements are descending; consecutive elements can be equal</td></tr>
<tr><td><code>"strictascend"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>elements are strictly ascending; consecutive elements cannot be equal</td></tr>
<tr><td><code>"strictdescend"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>elements are strictly descending; consecutive elements cannot be equal</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For matrices and vectors with complex numbers, order is checked via absolute values
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec a(10, fill::randu);
vec b = sort(a);

bool check1 = a.is_sorted();
bool check2 = b.is_sorted();


mat A(10, 10, fill::randu);

// check whether each column is sorted in descending manner
cout &lt;&lt; A.is_sorted("descend") &lt;&lt; endl;

// check whether each row is sorted in ascending manner
cout &lt;&lt; A.is_sorted("ascend", 1) &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sort">sort()</a></li>
<li><a href="#sort_index">sort_index()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_trimat"></a>
<b>.is_trimatu()</b>
<br>
<b>.is_trimatl()</b>
<ul>
<li>
Member functions of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li><i>.is_trimatu()</i>:
<ul>
<li>return <i>true</i> if the matrix is upper triangular, ie. the matrix is square sized and all elements below the main diagonal are zero; return <i>false</i> otherwise</li>
<li><b>caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on or above the main diagonal</li>
</ul>
</li>
<br>
<li><i>.is_trimatl()</i>:
<ul>
<li>return <i>true</i> if the matrix is lower triangular, ie. the matrix is square sized and all elements above the main diagonal are zero; return <i>false</i> otherwise</li>
<li><b>caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on or below the main diagonal</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = trimatl(A);

cout &lt;&lt; A.is_trimatu() &lt;&lt; endl;
cout &lt;&lt; B.is_trimatl() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#trimat">trimatu() / trimatl()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_diagmat">.is_diagmat()</a></li>
<li><a href="http://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_diagmat"></a>
<b>.is_diagmat()</b>
<ul>
<li>
Member function of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>Return <i>true</i> if the matrix is diagonal, ie. all elements outside of the main diagonal are zero
</li>
<br>
<li>Return <i>false</i> otherwise
</li>
<br>
<li>
<b>Caveat:</b> if this function returns <i>true</i>, do not assume that the matrix contains non-zero elements on the main diagonal
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = diagmat(A);

cout &lt;&lt; A.is_diagmat() &lt;&lt; endl;
cout &lt;&lt; B.is_diagmat() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="http://mathworld.wolfram.com/DiagonalMatrix.html">Diagonal matrix in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Diagonal_matrix">Diagonal matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_square"></a>
<b>.is_square()</b>
<ul>
<li>
Member function of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if the matrix is square, ie. number of rows is equal to the number of columns
</li>
<br>
<li>Returns <i>false</i> if the matrix is not square
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(6, 7, fill::randu);

cout &lt;&lt; A.is_square() &lt;&lt; endl;
cout &lt;&lt; B.is_square() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="#is_empty">.is_empty()</a></li>
<li><a href="#is_vec">.is_vec()</a></li>
<li><a href="#is_finite">.is_finite()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_symmetric"></a>
<b>.is_symmetric()</b>
<br><b>.is_symmetric(&nbsp;tol&nbsp;)</b>
<ul>
<li>
Member function of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if the matrix is symmetric</li>
<br>
<li>Returns <i>false</i> if the matrix is not symmetric</li>
<br>
<li>
The <i>tol</i> argument is optional; if <i>tol</i> is specified, the given matrix <i>X</i> is considered symmetric if <i>norm(X - X.st(), "inf") / norm (X, "inf") &leq; tol</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = A.t() * A;

cout &lt;&lt; A.is_symmetric() &lt;&lt; endl;
cout &lt;&lt; B.is_symmetric() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#is_square">.is_square()</a></li>
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/SymmetricMatrix.html">Symmetric matrix in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_hermitian"></a>
<b>.is_hermitian()</b>
<br><b>.is_hermitian(&nbsp;tol&nbsp;)</b>
<ul>
<li>
Member function of <i>Mat</i> and <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if the matrix is hermitian (self-adjoint)</li>
<br>
<li>Returns <i>false</i> if the matrix is not hermitian</li>
<br>
<li>
The <i>tol</i> argument is optional; if <i>tol</i> is specified, the given matrix <i>X</i> is considered hermitian if <i>norm(X - X.t(), "inf") / norm (X, "inf") &leq; tol</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
cx_mat A(5, 5, fill::randu);
cx_mat B = A.t() * A;

cout &lt;&lt; A.is_hermitian() &lt;&lt; endl;
cout &lt;&lt; B.is_hermitian() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#is_square">.is_square()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Hermitian_matrix">Hermitian matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/HermitianMatrix.html">Hermitian matrix in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_sympd"></a>
<b>.is_sympd()</b>
<br><b>.is_sympd(&nbsp;tol&nbsp;)</b>
<ul>
<li>
Member function of <i>Mat</i> and any dense matrix expression
</li>
<br>
<li>Returns <i>true</i> if the matrix is symmetric/hermitian positive definite within the tolerance given by <i>tol</i>
</li>
<br>
<li>Returns <i>false</i> otherwise
</li>
<br>
<li>
The <i>tol</i> argument is optional; if <i>tol</i> is not specified, by default <i>tol = 100 * datum::eps * norm(X, "fro")</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = A.t() * A;

cout &lt;&lt; A.is_sympd() &lt;&lt; endl;
cout &lt;&lt; B.is_sympd() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="#constants">datum::eps</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_zero"></a>
<b>.is_zero()</b>
<br>
<b>.is_zero(</b>&nbsp;tolerance&nbsp;<b>)</b>
<ul>
<li>For objects with non-complex elements: return <i>true</i> if each element has an absolute value &leq; <i>tolerance</i>; return <i>false</i> otherwise</li>
<br>
<li>For objects with complex elements: return <i>true</i> if for each element, each component (real and imaginary) has an absolute value &leq; <i>tolerance</i>; return <i>false</i> otherwise</li>
<br>
<li>The argument <i>tolerance</i> is optional; by default <i>tolerance&nbsp;=&nbsp;0</i></li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::zeros);

A(0,0) = datum::eps;

cout &lt;&lt; A.is_zero()           &lt;&lt; endl;
cout &lt;&lt; A.is_zero(datum::eps) &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#clean">.clean()</a></li>
<li><a href="#all">all()</a></li>
<li><a href="#constants">datum::eps</a></li>
<li><a href="#approx_equal">approx_equal()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="is_finite"></a>
<a name="is_finite_member"></a>
<b>.is_finite()</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if all elements of the object are finite
</li>
<br>
<li>Returns <i>false</i> if at least one of the elements of the object is non-finite (&plusmn;infinity or NaN)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::inf;

cout &lt;&lt; A.is_finite() &lt;&lt; endl;
cout &lt;&lt; B.is_finite() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#has_inf">.has_inf()</a></li>
<li><a href="#has_nan">.has_nan()</a></li>
<li><a href="#find_finite">find_finite()</a></li>
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="has_inf"></a>
<b>.has_inf()</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if at least one of the elements of the object is &plusmn;infinity
</li>
<br>
<li>Returns <i>false</i> otherwise
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::inf;

cout &lt;&lt; A.has_inf() &lt;&lt; endl;
cout &lt;&lt; B.has_inf() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#has_nan">.has_nan()</a>
<li><a href="#replace">.replace()</a></li>
<li><a href="#is_finite">.is_finite()</a>
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="has_nan"></a>
<b>.has_nan()</b>
<ul>
<li>
Member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i>, <i>SpMat</i>
</li>
<br>
<li>Returns <i>true</i> if at least one of the elements of the object is NaN (not-a-number)
</li>
<br>
<li>Returns <i>false</i> otherwise
</li>
<br>
<li>
<b>Caveat:</b>
<code>NaN</code> is not equal to anything, even itself
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

B(1,1) = datum::nan;

cout &lt;&lt; A.has_nan() &lt;&lt; endl;
cout &lt;&lt; B.has_nan() &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#has_inf">.has_inf()</a>
<li><a href="#replace">.replace()</a></li>
<li><a href="#is_finite">.is_finite()</a>
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="print"></a>
<b>.print()</b>
<br><b>.print( header )</b>
<br>
<br><b>.print( stream )</b>
<br><b>.print( stream, header )</b>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i>, <i>Cube</i> and <i>field</i>
</li>
<br>
<li>
Print the contents of an object to the <i>std::cout</i> stream (default),
or a user specified stream, with an optional header string
</li>
<br>
<li>
Objects can also be printed using the &lt;&lt; stream operator
</li>
<br>
<li>
Elements of a field can only be printed if there is an associated <i>operator&lt;&lt;</i> function defined
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(6, 6, fill::randu);

A.print();

// print a transposed version of A
A.t().print();

// "B:" is the optional header line
B.print("B:");

cout &lt;&lt; A &lt;&lt; endl;

cout &lt;&lt; "B:" &lt;&lt; endl;
cout &lt;&lt; B &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#raw_print">.raw_print()</a></li>
<li><a href="#save_load_mat">saving &amp; loading matrices</a></li>
<li><a href="#element_initialisation">initialising elements</a></li>
<li><a href="#logging">logging of errors and warnings</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="raw_print"></a>
<b>.raw_print()</b>
<br><b>.raw_print( header )</b>
<br>
<br><b>.raw_print( stream )</b>
<br><b>.raw_print( stream, header )</b>
<ul>
<li>
Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i> and <i>Cube</i>
</li>
<br>
<li>
Similar to the <a href="#print">.print()</a> member function,
with the difference that no formatting of the output is done; the stream's parameters such as precision, cell width, etc. can be set manually
</li>
<br>
<li>
If the cell width is set to zero, a space is printed between the elements
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

cout.precision(11);
cout.setf(ios::fixed);

A.raw_print(cout, "A:");
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#print">.print()</a></li>
<li><a href="http://en.cppreference.com/w/cpp/io/ios_base/fmtflags">std::ios_base::fmtflags</a> (cppreference.com)</li>
<li><a href="http://www.cplusplus.com/reference/ios/ios_base/fmtflags/">std::ios_base::fmtflags</a> (cplusplus.com)</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="save_load_mat"></a>
<b>saving/loading matrices &amp; cubes</b>
<br>
<br>
<table>
<tbody>
<tr>
<td>
<b>.save(</b> filename <b>)</b>
<br><b>.save(</b> filename<b>,</b> file_type <b>)</b>
<br>
<br><b>.save(</b> stream <b>)</b>
<br><b>.save(</b> stream<b>,</b> file_type <b>)</b>
<br>
<br><b>.save( hdf5_name(</b>filename<b>,</b> dataset<b>) )</b>
<br><b>.save( hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>) )</b>
<br>
<br><b>.save( csv_name(</b>filename<b>,</b> header<b>) )</b>
<br><b>.save( csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>) )</b>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
<b>.load(</b> filename <b>)</b>
<br><b>.load(</b> filename<b>,</b> file_type <b>)</b>
<br>
<br><b>.load(</b> stream <b>)</b>
<br><b>.load(</b> stream<b>,</b> file_type <b>)</b>
<br>
<br><b>.load( hdf5_name(</b>filename<b>,</b> dataset<b>) )</b>
<br><b>.load( hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>) )</b>
<br>
<br><b>.load( csv_name(</b>filename<b>,</b> header<b>) )</b>
<br><b>.load( csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>) )</b>
</td>
</tr>
</tbody>
</table>
<br>
<ul>
<li>Member functions of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>Cube</i> and <i>SpMat</i></li>
<br>
<li>Store/retrieve data in a file or stream (<b>caveat:</b> the stream must be opened in binary mode)</li>
<br>
<li>On success, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>true</i></li>
<br>
<li>On failure, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>false</i>; additionally, <i>.load()</i> resets the object so that it has no elements</li>
<br>
<li>
<i>file_type</i> can be one of the following:
<br>
<br>
<ul>
                  <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
                    <tbody>
                      <tr>
                        <td style="vertical-align: top;"><b>auto_detect</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Used only by <i>.load()</i> only: attempt to automatically detect the file type as one of the formats described below;
<br>[&nbsp;default operation for <i>.load()</i>&nbsp;]<br><br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>arma_binary</b><br></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in machine dependent binary format, with a simple header to speed up loading.
The header indicates the type and size of matrix/cube.
<br>[&nbsp;default operation for <i>.save()</i>&nbsp;]
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>arma_ascii</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in human readable text format, with a simple header to speed up loading.
The header indicates the type and size of matrix/cube.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>raw_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in machine dependent raw binary format, without a header.
Matrices are loaded to have one column,
while cubes are loaded to have one slice with one column.
The <a href="#reshape_member">.reshape()</a> function can be used to alter the size of the loaded matrix/cube without losing data.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>raw_ascii</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in raw ASCII format, without a header.
The numbers are separated by whitespace.
The number of columns must be the same in each row.
Cubes are loaded as one slice.
Data which was saved in Matlab/Octave using the <i>-ascii</i> option can be read in Armadillo, except for complex numbers.
Complex numbers are stored in standard C++ notation, which is a tuple surrounded by brackets: eg. (1.23,4.56) indicates 1.24&nbsp;+&nbsp;4.56i.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>csv_ascii</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in comma separated value (CSV) text format, <b>without</b> a header.
To save/load <b>with</b> a header, use the <b>csv_name(</b>filename,header<b>)</b> specification instead (more details below).
Applicable to <i>Mat</i> and <i>SpMat</i>.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>coord_ascii</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored as a text file in coordinate list format, without a header.
Only non-zero values are stored.
Applicable only to sparse matrices (<a href="#SpMat">SpMat</a>).
<br>
For real matrices, each line contains information in the following format:&nbsp; <code>row column value</code>
<br>For complex matrices, each line contains information in the following format:&nbsp; <code>row column real_value imag_value</code>
<br>The rows and columns start at zero. 
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>pgm_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Image data stored in Portable Gray Map (PGM) format.
Applicable to <i>Mat</i> only.
Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation, as each element is copied and converted to an 8 bit representation.
As such the matrix should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>ppm_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Image data stored in Portable Pixel Map (PPM) format.
Applicable to <i>Cube</i> only.
Saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation, as each element is copied and converted to an 8 bit representation.
As such the cube/field should have values in the [0,255] interval, otherwise the resulting image may not display correctly.
<br>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>hdf5_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
Numerical data stored in portable <a href="https://en.wikipedia.org/wiki/Hierarchical_Data_Format">HDF5</a> binary format.
<ul>
<li>
for saving, the default dataset name within the HDF5 file is "dataset"
</li>
<li>
for loading, the order of operations is:
(1) try loading a dataset named "dataset",
(2) try loading a dataset named "value",
(3) try loading the first available dataset
</li>
<li>
to explicitly control the dataset name, specify it via the <b>hdf5_name()</b> argument (more details below)
</li>
</ul>
                        </td>
                      </tr>
                    </tbody>
                  </table>
</ul>
</li>
<br>
<li>
By providing either <b>hdf5_name(</b>filename<b>,</b> dataset<b>)</b> or <b>hdf5_name(</b>filename<b>,</b> dataset<b>,</b> settings<b>)</b>, the <i>file_type</i> type is assumed to be <i>hdf5_binary</i>
<br>
<br>
<ul>
<li>
the <i>dataset</i> argument specifies an HDF5 dataset name (eg. "my_dataset") that can include a full path (eg. "/group_name/my_dataset");
if a blank dataset name is specified (ie.&nbsp;""), it is assumed to be "dataset"
<br>
<br>
</li>
<li>the <i>settings</i> argument is optional; it is one of the following, or a combination thereof:
<br>
<br>
<table>
<tr style="vertical-align: top;"><td><code>hdf5_opts::trans  </code></td><td>&nbsp;&nbsp;&nbsp;</td><td>save/load the data with columns transposed to rows (and vice versa)</td></tr>
<tr style="vertical-align: top;"><td><code>hdf5_opts::append </code></td><td>&nbsp;&nbsp;&nbsp;</td><td>instead of overwriting the file, append the specified dataset to the file;<br>the specified dataset must not already exist in the file</td></tr>
<tr style="vertical-align: top;"><td><code>hdf5_opts::replace</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>instead of overwriting the file, replace the specified dataset in the file<br><b>caveat:</b> HDF5 v1.8 may not automatically reclaim deleted space; use <a href="https://support.hdfgroup.org/HDF5/Tutor/cmdtooledit.html">h5repack</a> to clean HDF5 files</td></tr>
</table>
<br>
the above settings can be combined using the <code>+</code> operator; for example: <code>hdf5_opts::trans&nbsp;+&nbsp;hdf5_opts::append</code>
</li>
</ul>
</li>
<br>
<li>
<b>Caveat</b>:
for saving/loading HDF5 files, support for HDF5 must be enabled within Armadillo's <a href="#config_hpp">configuration</a>;
the <i>hdf5.h</i> header file must be available on your system and you will need to link with the HDF5 library (eg. <code><i>-lhdf5</i></code>)
</li>
<br>
<li>
By providing either <b>csv_name(</b>filename<b>,</b> header<b>)</b> or <b>csv_name(</b>filename<b>,</b> header<b>,</b> settings<b>)</b>,
the file is assumed to have data in comma separated value (CSV) text format
<br>
<br>
<ul>
<li>
the <i>header</i> argument specifies the object which stores the separate elements of the header line; it must have the type <code><a href="#field">field&lt;std::string&gt;</a></code>
<br>
<br>
</li>
<li>the optional <i>settings</i> argument is one of the following, or a combination thereof:
<br>
<br>
<table>
<tr style="vertical-align: top;"><td><code>csv_opts::trans    </code></td><td>&nbsp;&nbsp;&nbsp;</td><td>save/load the data with columns transposed to rows (and vice versa)</td></tr>
<tr style="vertical-align: top;"><td><code>csv_opts::no_header</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>assume there is no header line; the <i>header</i> argument is not referenced</td></tr>
</table>
<br>
the above settings can be combined using the <code>+</code> operator; for example: <code>csv_opts::trans&nbsp;+&nbsp;csv_opts::no_header</code>
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);

// default save format is arma_binary
A.save("A.bin");

// save in raw_ascii format
A.save("A.txt", raw_ascii);

// save in CSV format without a header
A.save("A.csv", csv_ascii);

// save in CSV format with a header
field&lt;std::string&gt; header(A.n_cols);
header(0) = "foo";
header(1) = "bar";  // etc
A.save( csv_name("A.csv", header) );

// save in HDF5 format with internal dataset named as "my_data"
A.save(hdf5_name("A.h5", "my_data"));

// automatically detect format type while loading
mat B;
B.load("A.bin");

// force loading in arma_ascii format
mat C;
C.load("A.txt", arma_ascii);


// example of testing for success
mat D;
bool ok = D.load("A.bin");

if(ok == false)
  {
  cout &lt;&lt; "problem with loading" &lt;&lt; endl;
  }
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="https://en.wikipedia.org/wiki/Hierarchical_Data_Format">HDF</a> in Wikipedia</li>
<li><a href="https://en.wikipedia.org/wiki/Comma-separated_values">CSV</a> in Wikipedia
<li><a href="#save_load_field">saving/loading fields</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="save_load_field"></a>
<b>saving/loading fields</b>
<br>
<br>
<table>
<tbody>
<tr>
<td>
<b>.save( name )</b>
<br><b>.save( name, file_type )</b>
<br>
<br><b>.save( stream )</b>
<br><b>.save( stream, file_type )</b>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
<b>.load( name )</b>
<br><b>.load( name, file_type )</b>
<br>
<br><b>.load( stream )</b>
<br><b>.load( stream, file_type )</b>
</td>
</tr>
</tbody>
</table>
<br>
<ul>
<li>Store/retrieve data in a file or stream (<b>caveat:</b> the stream must be opened in binary mode)</li>
<br>
<li>On success, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>true</i></li>
<br>
<li>On failure, <i>.save()</i> and <i>.load()</i> return a <i>bool</i> set to <i>false</i>; additionally, <i>.load()</i> resets the object so that it has no elements</li>
<br>
<li>
Fields with objects of type <i>std::string</i> are saved and loaded as raw text files.
The text files do not have a header.
Each string is separated by a whitespace.
<i>load()</i> will only accept text files that have the same number of strings on each line.
The strings can have variable lengths.
</li>
<br>
<li>
Other than storing string fields as text files, the following file formats are supported:
<br>
<br>
<ul>
                  <table style="text-align: left; width: 100%;" border="0" cellpadding="2" cellspacing="2">
                    <tbody>
                      <tr>
                        <td style="vertical-align: top;"><b>auto_detect</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
<br>
<li>
<i>.load()</i>: attempt to automatically detect the field format type as one of the formats described below;
this is the default operation
</li>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>arma_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
<br>
<li>
objects are stored in machine dependent binary format
<li>
default type for fields of type <i>Mat</i>, <i>Col</i>, <i>Row</i> or <i>Cube</i>
</li>
<li>
only applicable to fields of type <i>Mat</i>, <i>Col</i>, <i>Row</i> or <i>Cube</i>
</li>
<br>
                        </td>
                      </tr>
                      <tr>
                        <td style="vertical-align: top;"><b>ppm_binary</b></td>
                        <td style="vertical-align: top;"><br>
                        </td>
                        <td style="vertical-align: top;">
<br>
<li>
image data stored in Portable Pixmap Map (PPM) format
</li>
<li>
only applicable to fields of type <i>Mat</i>, <i>Col</i> or <i>Row</i>
</li>
<li>
<i>.load()</i>: loads the specified image and stores the red, green and blue components as three separate matrices;
the resulting field is comprised of the three matrices,
with the red, green and blue components in the first, second and third matrix, respectively
</li>
<li>
<i>.save()</i>: saves a field with exactly three matrices of equal size as an image;
it is assumed that the red, green and blue components are stored in the first, second and third matrix, respectively;
saving <i>int</i>, <i>float</i> or <i>double</i> matrices is a lossy operation,
as each matrix element is copied and converted to an 8 bit representation
</li>

                        </td>
                      </tr>
                    </tbody>
                  </table>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#save_load_mat">saving/loading matrices and cubes</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Generated Vectors/Matrices/Cubes</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="linspace"></a>
<b>linspace( start, end )</b>
<br><b>linspace( start, end, N )</b>
<ul>
<li>
Generate a vector with <i>N</i> elements;
the values of the elements are linearly spaced from <i>start</i> to (and including) <i>end</i>
</li>
<br>
<li>
The argument <i>N</i> is optional; by default <i>N = 100</i>
</li>
<br>
<li>
Usage:
<ul>
<li>vec v = linspace(start, end, N)</li>
<li><i>vector_type</i> v = linspace&lt;<i>vector_type</i>&gt;(start, end, N)</li>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> for <i>N&nbsp;=&nbsp;1</i>, the generated vector will have a single element equal to <i>end</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
   vec a = linspace(0, 5, 6);

rowvec b = linspace&lt;rowvec&gt;(5, 0, 6);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#regspace">regspace()</a></li>
<li><a href="#logspace">logspace()</a></li>
<li><a href="#randperm">randperm()</a></li>
<li><a href="#ones_standalone">ones()</a></li>
<li><a href="#interp1">interp1()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="logspace"></a>
<b>logspace( A, B )</b>
<br><b>logspace( A, B, N )</b>
<ul>
<li>
Generate a vector with <i>N</i> elements;
the values of the elements are logarithmically spaced from <i>10<sup><font size=-1>A</font></sup></i> to (and including) <i>10<sup><font size=-1>B</font></sup></i>
</li>
<br>
<li>
The argument <i>N</i> is optional; by default <i>N = 50</i>
</li>
<br>
<li>
Usage:
<ul>
<li>vec v = logspace(A, B, N)</li>
<li><i>vector_type</i> v = logspace&lt;<i>vector_type</i>&gt;(A, B, N)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
   vec a = logspace(0, 5, 6);

rowvec b = logspace&lt;rowvec&gt;(5, 0, 6);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#linspace">linspace()</a></li>
<li><a href="#regspace">regspace()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="regspace"></a>
<b>regspace( start, end )</b>
<br><b>regspace( start, delta, end )</b>
<ul>
<li>
Generate a vector with regularly spaced elements:
<br>[&nbsp;&nbsp;<i>(start&nbsp;+&nbsp;0*delta)</i>,&nbsp;&nbsp;<i>(start&nbsp;+&nbsp;1*delta)</i>,&nbsp;&nbsp;<i>(start&nbsp;+&nbsp;2*delta)</i>,&nbsp;&nbsp;<i>&#8943;</i>,&nbsp;&nbsp;<i>(start&nbsp;+&nbsp;M*delta)</i>&nbsp;&nbsp;]
<br>where <i>M&nbsp;=&nbsp;floor((end-start)/delta)</i>, so that <i>(start&nbsp;+&nbsp;M*delta)&nbsp;&le;&nbsp;end</i>
</li>
<br>
<li>
Similar in operation to the Matlab/Octave colon operator, ie. <i>start:end</i>&nbsp;&nbsp;and&nbsp;&nbsp;<i>start:delta:end</i>
</li>
<br>
<li>
If <i>delta</i> is not specified:
<ul>
<li><i>delta</i>&nbsp;=&nbsp;+1,       if <i>start&nbsp;&le;&nbsp;end</i></li>
<li><i>delta</i>&nbsp;=&nbsp;&minus;1, if <i>start&nbsp;&gt;&nbsp;end</i> &nbsp; (<b>caveat:</b> this is different to Matlab/Octave)</li>
</ul>
</li>
<br>
<li>
An empty vector is generated when one of the following conditions is true:
<ul>
<li><i>start&nbsp;&lt;&nbsp;end</i>, and <i>delta&nbsp;&lt;&nbsp;0</i></li>
<li><i>start&nbsp;&gt;&nbsp;end</i>, and <i>delta&nbsp;&gt;&nbsp;0</i></li>
<li><i>delta&nbsp;=&nbsp;0</i></li>
</ul>
</li>
<br>
<li>
Usage:
<ul>
<li>vec v = regspace(start, end)</li>
<li>vec v = regspace(start, delta, end)</li>
<li><i>vector_type</i> v = regspace&lt;<i>vector_type</i>&gt;(start, end)</li>
<li><i>vector_type</i> v = regspace&lt;<i>vector_type</i>&gt;(start, delta, end)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
 vec a = regspace(0,  9);             // 0,  1, ...,   9

uvec b = regspace&lt;uvec&gt;(2,  2,  10);  // 2,  4, ...,  10

ivec c = regspace&lt;ivec&gt;(0, -1, -10);  // 0, -1, ..., -10
</pre>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> do not use <i>regspace()</i> to specify ranges for contiguous submatrix views; use <a href="#submat">span()</a> instead
</li>
<br>
<li>
See also:
<ul>
<li><a href="#linspace">linspace()</a></li>
<li><a href="#logspace">logspace()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="randperm"></a>
<b>randperm( N )</b>
<br><b>randperm( N, M )</b>
<ul>
<li>
Generate a vector with a random permutation of integers from <i>0</i> to <i>N-1</i>
</li>
<br>
<li>
The optional argument <i>M</i> indicates the number of elements to return,
sampled without replacement from <i>0</i> to <i>N-1</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
uvec X = randperm(10);
uvec Y = randperm(10,2);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#randi">randi()</a></li>
<li><a href="#linspace">linspace()</a></li>
<li><a href="#regspace">regspace()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eye_standalone"></a>
<b>eye( n_rows, n_cols )</b>
<br>
<b>eye( size(X) )</b>
<ul>
<li>
Generate a matrix with the elements along the main diagonal set to one
and off-diagonal elements set to zero
</li>
<br>
<li>
An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i>
</li>
<br>
<li>
Usage:
<ul>
<li>mat X = eye( n_rows, n_cols )</li>
<li><i>matrix_type</i> X = eye&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> Y = eye&lt;<i>matrix_type</i>&gt;( size(X) )</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
   mat A = eye(5,5);  // or:  mat A(5,5,fill::eye);

  fmat B = 123.0 * eye&lt;fmat&gt;(5,5);

cx_mat C = eye&lt;cx_mat&gt;( size(B) );
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#eye_member">.eye()</a> (member function of Mat)</li>
<li><a href="#diag">.diag()</a></li>
<li><a href="#ones_standalone">ones()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#speye">speye()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="ones_standalone"></a>
<b>
ones( n_elem )
<br>ones( n_rows, n_cols )
<br>ones( n_rows, n_cols, n_slices )
<br>ones( size(X) )
</b>
<ul>
<li>
Generate a vector, matrix or cube with all elements set to one
</li>
<br>
<li>
Usage:
<ul>
<li><i>vector_type</i> v = ones&lt;<i>vector_type</i>&gt;( n_elem )</li>
<li><i>matrix_type</i> X = ones&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> Y = ones&lt;<i>matrix_type</i>&gt;( size(X) )</li>
<li><i>cube_type</i> Q = ones&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices )</li>
<li><i>cube_type</i> R = ones&lt;<i>cube_type</i>&gt;( size(Q) )</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec  v = ones&lt;vec&gt;(10);
uvec u = ones&lt;uvec&gt;(11);
mat  A = ones&lt;mat&gt;(5,6);
cube Q = ones&lt;cube&gt;(5,6,7);

mat  B = 123.0 * ones&lt;mat&gt;(5,6);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li>
<li><a href="#eye_standalone">eye()</a></li>
<li><a href="#linspace">linspace()</a></li>
<li><a href="#regspace">regspace()</a></li>
<li><a href="#randperm">randperm()</a></li>
<li><a href="#zeros_standalone">zeros()</a></li>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a></li>
<li><a href="#spones">spones()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="zeros_standalone"></a>
<b>zeros( n_elem )</b>
<br><b>zeros( n_rows, n_cols )</b>
<br><b>zeros( n_rows, n_cols, n_slices )</b>
<br><b>zeros( size(X) )</b>
<ul>
<li>
Generate a vector, matrix or cube with the elements set to zero
</li>
<br>
<li>
Usage:
<ul>
<li><i>vector_type</i> v = zeros&lt;<i>vector_type</i>&gt;( n_elem )</li>
<li><i>matrix_type</i> X = zeros&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> Y = zeros&lt;<i>matrix_type</i>&gt;( size(X) )</li>
<li><i>cube_type</i> Q = zeros&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices )</li>
<li><i>cube_type</i> R = zeros&lt;<i>cube_type</i>&gt;( size(Q) )</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec  v = zeros&lt;vec&gt;(10);
uvec u = zeros&lt;uvec&gt;(11);
mat  A = zeros&lt;mat&gt;(5,6);
cube Q = zeros&lt;cube&gt;(5,6,7);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#zeros_member">.zeros()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i>, <i>SpMat</i> and <i>Cube</i>)</li>
<li><a href="#ones_member">.ones()</a> (member function of <i>Mat</i>, <i>Col</i>, <i>Row</i> and <i>Cube</i>)</li>
<li><a href="#ones_standalone">ones()</a></li>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="randu_randn_standalone"></a>
<b>randu( )</b>
<br><b>randu( n_elem )</b>
<br><b>randu( n_rows, n_cols )</b>
<br><b>randu( n_rows, n_cols, n_slices )</b>
<br><b>randu( size(X) )</b>
<br>
<br><b>randn( )</b>
<br><b>randn( n_elem )</b>
<br><b>randn( n_rows, n_cols )</b>
<br><b>randn( n_rows, n_cols, n_slices )</b>
<br><b>randn( size(X) )</b>
<ul>
<li>
Generate a scalar, vector, matrix or cube with the elements set to random <b>floating point</b> values
</li>
<br>
<li><i>randu()</i> uses a uniform distribution in the [0,1] interval
</li>
<br>
<li><i>randn()</i> uses a normal/Gaussian distribution with zero mean and unit variance
</li>
<br>
<li>
Usage:
<ul>
<li><i>scalar_type</i> s = randu&lt;<i>scalar_type</i>&gt;( ), where <i>scalar_type</i> &in; { float, double, <a href="#cx_double">cx_float</a>, <a href="#cx_double">cx_double</a> }</li>
<li><i>vector_type</i> v = randu&lt;<i>vector_type</i>&gt;( n_elem )</li>
<li><i>matrix_type</i> X = randu&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> Y = randu&lt;<i>matrix_type</i>&gt;( size(X) )</li>
<li><i>cube_type</i> Q = randu&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices )</li>
<li><i>cube_type</i> R = randu&lt;<i>cube_type</i>&gt;( size(Q) )</li>
</ul>
</li>
<br>
<li>
To change the RNG seed, use <i>arma_rng::set_seed(value)</i> or <i>arma_rng::set_seed_random()</i> functions
</li>
<br>
<li>
<b>Caveat:</b> to generate a matrix with random integer values instead of floating point values,
use <a href="#randi">randi()</a> instead 
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec  v = randu&lt;vec&gt;(5);
mat  A = randu&lt;mat&gt;(5,6);
cube Q = randu&lt;cube&gt;(5,6,7);

arma_rng::set_seed_random();  // set the seed to a random value
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#randu_randn_member">.randu() &amp; .randn()</a> (member functions)</li>
<li><a href="#randi">randi()</a></li>
<li><a href="#randg">randg()</a></li>
<li><a href="#mvnrnd">mvnrnd()</a></li>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#ones_standalone">ones()</a></li>
<li><a href="#zeros_standalone">zeros()</a></li>
<li><a href="#shuffle">shuffle()</a></li>
<li><a href="#sprandu_sprandn">sprandu() &amp; sprandn()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="randg"></a>
<b>randg( )</b> 
<br><b>randg( distr_param(a,b) )</b> 
<br>
<br><b>randg( n_elem )</b> 
<br><b>randg( n_elem, distr_param(a,b) )</b> 
<br>
<br><b>randg( n_rows, n_cols )</b>
<br><b>randg( n_rows, n_cols, distr_param(a,b) )</b>
<br>
<br><b>randg( n_rows, n_cols, n_slices )</b>
<br><b>randg( n_rows, n_cols, n_slices, distr_param(a,b) )</b>
<br>
<br><b>randg( size(X) )</b>
<br><b>randg( size(X), distr_param(a,b) )</b>
<ul>
<li>
Generate a scalar, vector, matrix or cube with the elements set to random values from a gamma distribution:
<ul>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;"><i>x<sup>&thinsp;a-1</sup> exp(&thinsp;-x&thinsp;/&thinsp;b&thinsp;)</i></td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>p<font size=+1>(</font>x|a,b<font size=+1>)</font></i></td><td style="vertical-align: top;">&nbsp;<font size=+1>=</font>&nbsp;</td><td style="vertical-align: top;"><font size=+1><b><hr></b></font></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top; text-align: center;"><i>b<sup>&thinsp;a</sup>&nbsp;&Gamma;(a)</i></td>
    </tr>
  </tbody>
</table>
</ul>
where <i>a</i> is the shape parameter and <i>b</i> is the scale parameter, with constraints <i>a &gt; 0</i> and <i>b &gt; 0</i>
</li>
<br>
<li>The default distribution parameters are <i>a=1</i> and <i>b=1</i>
</li>
<br>
<li>
Usage:
<ul>
<li><i>scalar_type</i> s = randg&lt;<i>scalar_type</i>&gt;( ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
<li><i>scalar_type</i> s = randg&lt;<i>scalar_type</i>&gt;( distr_param(a,b) ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
<br>
<li><i>vector_type</i> v = randg&lt;<i>vector_type</i>&gt;( n_elem )</li>
<li><i>vector_type</i> v = randg&lt;<i>vector_type</i>&gt;( n_elem, distr_param(a,b) )</li>
<br>
<li><i>matrix_type</i> X = randg&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> X = randg&lt;<i>matrix_type</i>&gt;( n_rows, n_cols, distr_param(a,b) )</li>
<li><i>matrix_type</i> Y = randg&lt;<i>matrix_type</i>&gt;( size(X) )</li>
<li><i>matrix_type</i> Y = randg&lt;<i>matrix_type</i>&gt;( size(X), distr_param(a,b) )</li>
<br>
<li><i>cube_type</i> Q = randg&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices )</li>
<li><i>cube_type</i> Q = randg&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices, distr_param(a,b) )</li>
<li><i>cube_type</i> R = randg&lt;<i>cube_type</i>&gt;( size(Q) )</li>
<li><i>cube_type</i> R = randg&lt;<i>cube_type</i>&gt;( size(Q), distr_param(a,b) )</li>
</ul>
</li>
<br>
<li>
To change the RNG seed, use <i>arma_rng::set_seed(value)</i> or <i>arma_rng::set_seed_random()</i> functions
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec v = randg&lt;vec&gt;(100, distr_param(2,1));

mat X = randg&lt;mat&gt;(10, 10, distr_param(2,1));
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a></li>
<li><a href="#randi">randi()</a></li>
<li><a href="#chi2rnd">chi2rnd()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Gamma_distribution">gamma distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="randi"></a>
<b>randi( )</b> 
<br><b>randi( distr_param(a,b) )</b> 
<br>
<br><b>randi( n_elem )</b> 
<br><b>randi( n_elem, distr_param(a,b) )</b> 
<br>
<br><b>randi( n_rows, n_cols )</b>
<br><b>randi( n_rows, n_cols, distr_param(a,b) )</b>
<br>
<br><b>randi( n_rows, n_cols, n_slices )</b>
<br><b>randi( n_rows, n_cols, n_slices, distr_param(a,b) )</b>
<br>
<br><b>randi( size(X) )</b>
<br><b>randi( size(X), distr_param(a,b) )</b>
<ul>
<li>
Generate a scalar, vector, matrix or cube with the elements set to random <b>integer</b> values in the [a,b] interval
</li>
<br>
<li>The default distribution parameters are <i>a=0</i> and <i>b=maximum_int</i>
</li>
<br>
<li>
Usage:
<ul>
<li><i>scalar_type</i> v = randi&lt;<i>scalar_type</i>&gt;( )</li>
<li><i>scalar_type</i> v = randi&lt;<i>scalar_type</i>&gt;( distr_param(a,b) )</li>
<br>
<li><i>vector_type</i> v = randi&lt;<i>vector_type</i>&gt;( n_elem )</li>
<li><i>vector_type</i> v = randi&lt;<i>vector_type</i>&gt;( n_elem, distr_param(a,b) )</li>
<br>
<li><i>matrix_type</i> X = randi&lt;<i>matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>matrix_type</i> X = randi&lt;<i>matrix_type</i>&gt;( n_rows, n_cols, distr_param(a,b) )</li>
<li><i>matrix_type</i> Y = randi&lt;<i>matrix_type</i>&gt;( size(X) )</li>
<li><i>matrix_type</i> Y = randi&lt;<i>matrix_type</i>&gt;( size(X), distr_param(a,b) )</li>
<br>
<li><i>cube_type</i> Q = randi&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices )</li>
<li><i>cube_type</i> Q = randi&lt;<i>cube_type</i>&gt;( n_rows, n_cols, n_slices, distr_param(a,b) )</li>
<li><i>cube_type</i> R = randi&lt;<i>cube_type</i>&gt;( size(Q) )</li>
<li><i>cube_type</i> R = randi&lt;<i>cube_type</i>&gt;( size(Q), distr_param(a,b) )</li>
</ul>
</li>
<br>
<li>
To change the RNG seed, use <i>arma_rng::set_seed(value)</i> or <i>arma_rng::set_seed_random()</i> functions
</li>
<br>
<li>
<b>Caveat:</b> to generate a continuous distribution with floating point values (ie. <i>float</i> or <i>double</i>), use <a href="#randu_randn_standalone">randu()</a> instead 
</li>
<br>
<li>
Examples:
<ul>
<pre>
imat A = randi&lt;imat&gt;(5, 6);

imat A = randi&lt;imat&gt;(6, 7, distr_param(-10, +20));

arma_rng::set_seed_random();  // set the seed to a random value
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a></li>
<li><a href="#randg">randg()</a></li>
<li><a href="#randperm">randperm()</a></li>
<li><a href="#imbue">.imbue()</a></li>
<li><a href="#ones_standalone">ones()</a></li>
<li><a href="#zeros_standalone">zeros()</a></li>
<li><a href="#shuffle">shuffle()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="speye"></a>
<b>speye( n_rows, n_cols )</b>
<br>
<b>speye( size(X) )</b>
<ul>
<li>
Generate a sparse matrix with the elements along the main diagonal set to one
and off-diagonal elements set to zero
</li>
<br>
<li>
An identity matrix is generated when <i>n_rows</i> = <i>n_cols</i>
</li>
<br>
<li>
Usage:
<ul>
<li><i>sparse_matrix_type</i> X = speye&lt;<i>sparse_matrix_type</i>&gt;( n_rows, n_cols )</li>
<li><i>sparse_matrix_type</i> Y = speye&lt;<i>sparse_matrix_type</i>&gt;( size(X) )</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = speye&lt;sp_mat&gt;(5,5);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#spones">spones()</a></li>
<li><a href="#sprandu_sprandn">sprandu() &amp; sprandn()</a></li>
<li><a href="#eye_standalone">eye()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="spones"></a>
<b>spones( A )</b>
<ul>
<li>
Generate a sparse matrix with the same structure as sparse matrix <i>A</i>,
but with the non-zero elements set to one
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = sprandu&lt;sp_mat&gt;(100, 200, 0.1);

sp_mat B = spones(A);
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#speye">speye()</a></li>
<li><a href="#sprandu_sprandn">sprandu() &amp; sprandn()</a></li>
<li><a href="#ones_standalone">ones()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sprandu_sprandn"></a>
<b>sprandu( n_rows, n_cols, density )</b>
<br><b>sprandn( n_rows, n_cols, density )</b>
<br>
<br><b>sprandu( size(X), density )</b>
<br><b>sprandn( size(X), density )</b>
<ul>
<li>
Generate a sparse matrix with the non-zero elements set to random values
</li>
<br>
<li>
The <i>density</i> argument specifies the percentage of non-zero elements; it must be in the [0,1] interval
</li>
<br>
<li><i>sprandu()</i> uses a uniform distribution in the [0,1] interval
</li>
<br>
<li><i>sprandn()</i> uses a normal/Gaussian distribution with zero mean and unit variance
</li>
<br>
<li>
Usage:
<ul>
<li><i>sparse_matrix_type</i> X = sprandu&lt;<i>sparse_matrix_type</i>&gt;( n_rows, n_cols, density )</li>
<li><i>sparse_matrix_type</i> Y = sprandu&lt;<i>sparse_matrix_type</i>&gt;( size(X), density )</li>
</ul>
</li>
<br>
<li>
To change the RNG seed, use <i>arma_rng::set_seed(value)</i> or <i>arma_rng::set_seed_random()</i> functions
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = sprandu&lt;sp_mat&gt;(100, 200, 0.1);
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#speye">speye()</a></li>
<li><a href="#spones">spones()</a></li>
<li><a href="#randu_randn_standalone">randu() &amp; randn()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Uniform_distribution_(continuous)">uniform distribution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="toeplitz"></a>
<b>toeplitz( A )</b>
<br><b>toeplitz( A, B )</b>
<br><b>circ_toeplitz( A )</b>
<ul>
<li>
toeplitz(): generate a Toeplitz matrix, with the first column specified by <i>A</i>, and (optionally) the first row specified by <i>B</i>
</li>
<br>
<li>
circ_toeplitz(): generate a circulant Toeplitz matrix
</li>
<br>
<li>
A and B must be vectors
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec A(5, fill::randu);
mat X = toeplitz(A);
mat Y = circ_toeplitz(A);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="http://mathworld.wolfram.com/ToeplitzMatrix.html">Toeplitz matrix in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Toeplitz_matrix">Toeplitz matrix in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Circulant_matrix">Circulant matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Functions of Vectors/Matrices/Cubes</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="abs"></a>
<b>abs( X )</b>
<ul>
<li>
Obtain the magnitude of each element
</li>
<br>
<li>
Usage for non-complex X:
<ul>
<li>Y = abs(X)</li>
<li>X and Y must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
</ul>
</li>
<br>
<li>
Usage for complex X:
<ul>
<li><i>real_object_type</i> Y = abs(X)</li>
<li>The type of X must be a complex matrix or complex cube, such as <i>cx_mat</i> or <i>cx_cube</i></li>
<li>The type of Y must be the real counterpart to the type of X; if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = abs(A); 

cx_mat X(5, 5, fill::randu);
   mat Y = abs(X);
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#arg">arg()</a></li>
<li><a href="#conj">conj()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="accu"></a>
<b>accu( X )</b>
<ul>
<li>
Accumulate (sum) all elements of a vector, matrix or cube
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);
mat B(5, 6, fill::randu);

double x = accu(A);

double y = accu(A % B);

// accu(A % B) is a "multiply-and-accumulate" operation
// as operator % performs element-wise multiplication
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sum">sum()</a></li>
<li><a href="#cumsum">cumsum()</a></li>
<li><a href="#trace">trace()</a></li>
<li><a href="#stats_fns">mean()</a></li>
<li><a href="#dot">dot()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="affmul"></a>
<b>affmul( A, B )</b>
<ul>
<li>Multiply matrix <i>A</i> by an augmented form of <i>B</i>, where a row with ones is appended to B;<br>for example:</li>
<pre>
&#9121; A<sub>00</sub> A<sub>01</sub> A<sub>02</sub> &#9124;   &#9121; B<sub>0</sub> &#9124;
&#9122; A<sub>10</sub> A<sub>11</sub> A<sub>12</sub> &#9125; x &#9122; B<sub>1</sub> &#9125;
&#9123; A<sub>20</sub> A<sub>21</sub> A<sub>22</sub> &#9126;   &#9123; 1<sub> </sub> &#9126;
</pre>
<li><i>A</i> is typically an affine transformation matrix</li>
<br>
<li>The number of columns in <i>A</i> must be equal to number of rows in the augmented form of <i>B</i> (ie. A.n_cols = B.n_rows+1)</li>
<br>
<li><i>B</i> can be a vector or matrix</li>
<br>
<li>
Examples:
<ul>
<pre>
mat44 A; A.randu();
vec3  B; B.randu();

vec4  C = affmul(A,B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#operators">math operators</a></li>
<li><a href="https://en.wikipedia.org/wiki/Affine_transformation">Affine transformation in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Transformation_matrix">Transformation matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="all"></a>
<b>all( V )</b>
<br><b>all( X )</b>
<br><b>all( X, dim )</b>
<ul>
<li>For vector <i>V</i>, return <i>true</i> if all elements of the vector are non-zero or satisfy a relational condition</li>
<br>
<li>
For matrix <i>X</i> and
<ul>
<li>
<i>dim=0</i>, return a row vector (of type <a href="#Row">urowvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding column of <i>X</i> has all non-zero elements</li>
<li>
<i>dim=1</i>, return a column vector (of type <a href="#Col">ucolvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding row of <i>X</i> has all non-zero elements</li>
</ul>
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Relational operators can be used instead of <i>V</i> or <i>X</i>, eg.&nbsp;<i>A&nbsp;&gt;&nbsp;0.5</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec V(10,   fill::randu);
mat X(5, 5, fill::randu);


// status1 will be set to true if vector V has all non-zero elements
bool status1 = all(V);

// status2 will be set to true if vector V has all elements greater than 0.5
bool status2 = all(V &gt; 0.5);

// status3 will be set to true if matrix X has all elements greater than 0.6;
// note the use of vectorise()
bool status3 = all(vectorise(X) &gt; 0.6);

// generate a row vector indicating which columns of X have all elements greater than 0.7
umat A = all(X &gt; 0.7);

</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#any">any()</a></li>
<li><a href="#approx_equal">approx_equal()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#is_zero">.is_zero()</a></li>
<li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="any"></a>
<b>any( V )</b>
<br><b>any( X )</b>
<br><b>any( X, dim )</b>
<ul>
<li>For vector <i>V</i>, return <i>true</i> if any element of the vector is non-zero or satisfies a relational condition</li>
<br>
<li>
For matrix <i>X</i> and
<ul>
<li>
<i>dim=0</i>, return a row vector (of type <a href="#Row">urowvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding column of <i>X</i> has any non-zero elements</li>
<li>
<i>dim=1</i>, return a column vector (of type <a href="#Col">ucolvec</a> or <a href="#Mat">umat</a>),
with each element (0 or 1) indicating whether the corresponding row of <i>X</i> has any non-zero elements</li>
</ul>
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Relational operators can be used instead of <i>V</i> or <i>X</i>, eg.&nbsp;<i>A&nbsp;&gt;&nbsp;0.9</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec V(10,   fill::randu);
mat X(5, 5, fill::randu);


// status1 will be set to true if vector V has any non-zero elements
bool status1 = any(V);

// status2 will be set to true if vector V has any elements greater than 0.5
bool status2 = any(V &gt; 0.5);

// status3 will be set to true if matrix X has any elements greater than 0.6;
// note the use of vectorise()
bool status3 = any(vectorise(X) &gt; 0.6);

// generate a row vector indicating which columns of X have elements greater than 0.7
umat A = any(X &gt; 0.7);

</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#all">all()</a></li>
<li><a href="#approx_equal">approx_equal()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#conv_to">conv_to()</a> (convert between matrix/vector types)</li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="approx_equal"></a>
<b>approx_equal( A, B, method, tol )</b>
<br><b>approx_equal( A, B, method, abs_tol, rel_tol )</b>
<ul>
<li>
Return <i>true</i> if all corresponding elements in <i>A</i> and <i>B</i> are approximately equal
</li>
<br>
<li>
Return <i>false</i> if any of the corresponding elements in <i>A</i> and <i>B</i> are not approximately equal, or if <i>A</i> and <i>B</i> have different dimensions
</li>
<br>
<li>
The argument <i>method</i> controls how the approximate equality is determined; it is one of:
<ul>
<table>
<tbody>
<tr><td><code>"absdiff"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x&nbsp;&minus;&nbsp;y|&nbsp;&le;&nbsp;tol</i></td></tr>
<tr><td><code>"reldiff"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x&nbsp;&minus;&nbsp;y|&nbsp;/&nbsp;max(&nbsp;|x|,&nbsp;|y|&nbsp;)&nbsp;&le;&nbsp;tol</i></td></tr>
<tr><td><code>"both"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>scalars <i>x</i> and <i>y</i> are considered equal if <i>|x&nbsp;&minus;&nbsp;y|&nbsp;&le;&nbsp;abs_tol</i>&nbsp;&nbsp;<b>or</b>&nbsp;&nbsp;<i>|x&nbsp;&minus;&nbsp;y|&nbsp;/&nbsp;max(&nbsp;|x|,&nbsp;|y|&nbsp;)&nbsp;&le;&nbsp;rel_tol</i></td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = A + 0.001;

bool same1 = approx_equal(A, B, "absdiff", 0.002);


mat C = 1000 * randu&lt;mat&gt;(5,5);
mat D = C + 1;

bool same2 = approx_equal(C, D, "reldiff", 0.1);

bool same3 = approx_equal(C, D, "both", 2, 0.1);
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#all">all()</a></li>
<li><a href="#any">any()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#is_zero">.is_zero()</a></li>
<li><a href="#operators">relational operators</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="arg"></a>
<b>arg( X )</b>
<ul>
<li>
Obtain the phase angle (in radians) of each element
</li>
<br>
<li>
Usage for non-complex X:
<ul>
<li>Y = arg(X)</li>
<li>X and Y must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
<li>non-complex elements are treated as complex elements with zero imaginary component
</li>
</ul>
</li>
<br>
<li>
Usage for complex X:
<ul>
<li><i>real_object_type</i> Y = arg(X)</li>
<li>The type of X must be a complex matrix or complex cube, such as <i>cx_mat</i> or <i>cx_cube</i></li>
<li>The type of Y must be the real counterpart to the type of X; if X has the type <i>cx_mat</i>, then the type of Y must be <i>mat</i>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
cx_mat A(5, 5, fill::randu);
   mat B = arg(A); 
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#abs">abs()</a></li>
<li><a href="#trig_fns">atan2()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Argument_(complex_analysis)">Argument (complex analysis) in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/ComplexArgument.html">Complex Argument in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="as_scalar"></a>
<b>as_scalar( expression )</b>
<ul>
<li>
Evaluate an expression that results in a 1x1 matrix,
followed by converting the 1x1 matrix to a pure scalar
</li>
<br>
<li>
Optimised expression evaluations are automatically used when a binary or trinary expression is given (ie. 2 or 3 terms)
</li>
<br>
<li>
Examples:
<ul>
<pre>
rowvec r(5, fill::randu);
colvec q(5, fill::randu);

mat X(5, 5, fill::randu);

// examples of expressions which have optimised implementations

double a = as_scalar(r*q);
double b = as_scalar(r*X*q);
double c = as_scalar(r*diagmat(X)*q);
double d = as_scalar(r*inv(diagmat(X))*q);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#accu">accu()</a></li>
<li><a href="#trace">trace()</a></li>
<li><a href="#dot">dot()</a></li>
<li><a href="#norm">norm()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="clamp"></a>
<b>clamp( X, min_val, max_val )</b>
<ul>
<li>
Create a copy of <i>X</i> with each element clamped to the [<i>min_val</i>,&nbsp;<i>max_val</i>] interval;
<br>any value lower than <i>min_val</i> will be set to <i>min_val</i>, and any value higher than <i>max_val</i> will be set to <i>max_val</i>
</li>
<br>
<li>
If <i>X</i> is a sparse matrix, clamping is applied only to the non-zero elements
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = clamp(A, 0.2,     0.8); 

mat C = clamp(A, A.min(), 0.8); 

mat D = clamp(A, 0.2, A.max()); 
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#min_and_max_member">.min() &amp; .max()</a></li>
<li><a href="#clean">.clean()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#find">find()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cond"></a>
<b>cond( A )</b>
<ul>
<li>
Return the condition number of matrix <i>A</i> (the ratio of the largest singular value to the smallest)
</li>
<br>
<li>
Large condition numbers suggest that matrix <i>A</i> is nearly singular
</li>
<br>
<li>
The computation is based on singular value decomposition; if the decomposition fails, a <i>std::runtime_error</i> exception is thrown
</li>
<br>
<li>
<b>Caveat:</b> the <a href="#rcond">rcond()</a> function is faster for providing an estimate of the reciprocal of the condition number
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat    A(5, 5, fill::randu);
double c = cond(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#rcond">rcond()</a></li>
<li><a href="#rank">rank()</a></li>
<li><a href="#inv">inv()</a></li>
<li><a href="#solve">solve()</a></li>
<li><a href="http://mathworld.wolfram.com/ConditionNumber.html">condition number in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Condition_number">condition number in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="conj"></a>
<b>conj( X )</b>
<ul>
<li>
Obtain the complex conjugate of each element in a complex matrix or cube
</li>
<br>
<li>
Examples:
<ul>
<pre>
cx_mat X(5, 5, fill::randu);
cx_mat Y = conj(X);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#abs">abs()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#trans">trans()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="conv_to"></a>
<b>
conv_to&lt; <i>type</i> &gt;::from( X )
</b>
<ul>
<li>
Convert from one matrix type to another (eg. <i>mat</i> to <i>imat</i>), or one cube type to another (eg. <i>cube</i> to <i>icube</i>)
</li>
<br>
<li>
Conversion between <i>std::vector</i> and Armadillo matrices/vectors is also possible
</li>
<br>
<li>
Conversion of a <i>mat</i> object into <i>colvec</i>, <i>rowvec</i> or <i>std::vector</i> is possible if the object can be interpreted as a vector
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat  A(5, 5, fill::randu);
fmat B = conv_to&lt;fmat&gt;::from(A);

typedef std::vector&lt;double&gt; stdvec;

stdvec x(3);
x[0] = 0.0; x[1] = 1.0;  x[2] = 2.0;

colvec y = conv_to&lt; colvec &gt;::from(x);
stdvec z = conv_to&lt; stdvec &gt;::from(y); 
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#abs">abs()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#adv_constructors_mat">advanced constructors (matrices)</a></li>
<li><a href="#adv_constructors_cube">advanced constructors (cubes)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cross"></a>
<b>cross( A, B )</b>
<ul>
<li>
Calculate the cross product between A and B, under the assumption that A and B are 3 dimensional vectors
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec a(3, fill::randu);
vec b(3, fill::randu);

vec c = cross(a,b);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#dot">dot()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Cross_product">Cross product in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/CrossProduct.html">Cross product in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cumsum"></a>
<b>cumsum( V )</b>
<br><b>cumsum( X )</b>
<br><b>cumsum( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, return a vector of the same orientation, containing the cumulative sum of elements
</li>
<br>
<li>
For matrix <i>X</i>, return a matrix containing the cumulative sum of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = cumsum(A);
mat C = cumsum(A, 1);

vec x(10, fill::randu);
vec y = cumsum(x);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cumprod">cumprod()</a></li>
<li><a href="#accu">accu()</a></li>
<li><a href="#sum">sum()</a></li>
<li><a href="#diff">diff()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cumprod"></a>
<b>cumprod( V )</b>
<br><b>cumprod( X )</b>
<br><b>cumprod( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, return a vector of the same orientation, containing the cumulative product of elements
</li>
<br>
<li>
For matrix <i>X</i>, return a matrix containing the cumulative product of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = cumprod(A);
mat C = cumprod(A, 1);

vec x(10, fill::randu);
vec y = cumprod(x);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cumsum">cumsum()</a></li>
<li><a href="#prod">prod()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="det"></a>
<b>det( A )</b>
<ul>
<li>
Determinant of square matrix <i>A</i>
</li>
<br>
<li>
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>
<b>Caveat</b>: for large matrices <i><a href="#log_det">log_det()</a></i> is more precise than <i>det()</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double x = det(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#log_det">log_det()</a></li>
<li><a href="#rcond">rcond()</a></li>
<li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="diagmat"></a>
<b>diagmat( V )</b>
<br><b>diagmat( V, k )</b>
<br>
<br><b>diagmat( X )</b>
<br><b>diagmat( X, k )</b>
<ul>
<li>
Generate a diagonal matrix from vector <i>V</i> or matrix <i>X</i>
</li>
<br>
<li>
Given vector <i>V</i>, generate a square matrix with the <i>k</i>-th diagonal containing a copy of the vector; all other elements are set to zero
</li>
<br>
<li>
Given matrix <i>X</i>, generate a matrix with the <i>k</i>-th diagonal containing a copy of the <i>k</i>-th diagonal of <i>X</i>; all other elements are set to zero
</li>
<br>
<li>
The argument <i>k</i> is optional; by default the main diagonal is used (<i>k=0</i>)
</li>
<br>
<li>
For <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is used (above main diagonal, towards top-right corner)
</li>
<br>
<li>
For <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is used (below main diagonal, towards bottom-left corner)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = diagmat(A);
mat C = diagmat(A,1);

vec v(5, fill::randu);
mat D = diagmat(v);
mat E = diagmat(v,1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#diag">.diag()</a></li>
<li><a href="#is_diagmat">.is_diagmat()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#trimat">trimatu() / trimatl()</a></li>
<li><a href="#symmat">symmatu() / symmatl()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Diagonal_matrix">diagonal matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="diagvec"></a>
<b>diagvec( A )</b>
<br><b>diagvec( A, k )</b>
<ul>
<li>
Extract the <i>k</i>-th diagonal from matrix <i>A</i>
</li>
<br>
<li>
The argument <i>k</i> is optional; by default the main diagonal is extracted (<i>k=0</i>)
</li>
<br>
<li>For <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is extracted (top-right corner)</li>
<br>
<li>For <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is extracted (bottom-left corner)</li>
<br>
<li>
The extracted diagonal is interpreted as a column vector
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

vec d = diagvec(A);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#diag">.diag()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#trace">trace()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="diff"></a>
<b>diff( V )</b>
<br><b>diff( V, k )</b>
<br>
<br><b>diff( X )</b>
<br><b>diff( X, k )</b>
<br><b>diff( X, k, dim )</b>
<ul>
<li>
For vector <i>V</i>, return a vector of the same orientation, containing the differences between consecutive elements
</li>
<br>
<li>
For matrix <i>X</i>, return a matrix containing the differences between consecutive elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The optional argument <i>k</i> indicates that the differences are calculated recursively <i>k</i> times; by default <i>k=1</i> is used
</li>
<br>
<li>
The resulting number of differences is <i>n - k</i>, where <i>n</i> is the number of elements; if <i>n &le; k</i>, the number of differences is zero (ie. an empty vector/matrix is returned)
</li>
<br>
<li>
The argument <i>dim</i> is optional; by default <i>dim=0</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec a = linspace&lt;vec&gt;(1,10,10);

vec b = diff(a);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#trapz">trapz()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Numerical_differentiation">numerical differentiation in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/NumericalDifferentiation.html">numerical differentiation in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="dot"></a>
<b>dot( A, B )</b>
<br><b>cdot( A, B )</b>
<br><b>norm_dot( A, B )</b>
<ul>
<li>
<i>dot(A,B)</i>: dot product of <i>A</i> and <i>B</i>, treating <i>A</i> and <i>B</i> as vectors
</li>
<br>
<li>
<i>cdot(A,B)</i>: as per <i>dot(A,B)</i>, but the complex conjugate of <i>A</i> is used
</li>
<br>
<li>
<i>norm_dot(A,B)</i>: normalised dot product; equivalent to <i>dot(A,B)&nbsp;/&nbsp;(&#8741;A&#8741;&#8226;&#8741;B&#8741;)</i>
</li>
<br>
<li>
<b>Caveat:</b> <a href="#norm">norm()</a> is more robust for calculating the norm, as it handles underflows and overflows
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec a(10, fill::randu);
vec b(10, fill::randu);

double x = dot(a,b);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#norm">norm()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#cross">cross()</a></li>
<li><a href="#conj">conj()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eps"></a>
<b>eps( X )</b>
<ul>
<li>
Obtain the positive distance of the absolute value of each element of <i>X</i> to the next largest representable floating point number
</li>
<br>
<li>
<i>X</i> can be a scalar (eg. <i>double</i>), vector or matrix
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B = eps(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#constants">datum::eps</a></li>
<li><a href="http://mathworld.wolfram.com/Floating-PointArithmetic.html">Floating-Point Arithmetic in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/IEEE_754-2008">IEEE Standard for Floating-Point Arithmetic in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="expmat"></a>
<b>B = expmat( A )</b>
<br><b>expmat( B, A )</b>
<ul>
<li>Matrix exponential of general square matrix <i>A</i></li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the matrix exponential cannot be found:
<ul>
<li><i>B = expmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>expmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li><b>Caveat</b>: if matrix <i>A</i> is symmetric, using <a href="#expmat_sym">expmat_sym()</a> is faster</li>
<br>
<li><b>Caveat</b>: the matrix exponential operation is generally <b>not</b> the same as applying the <a href="#misc_fns">exp()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = expmat(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#expmat_sym">expmat_sym()</a></li>
<li><a href="#logmat">logmat()</a></li>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="http://en.wikipedia.org/wiki/Matrix_exponential">matrix exponential in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixExponential.html">matrix exponential in MathWorld</a></li>
<li><a href="http://doi.org/10.1137/S00361445024180">Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="expmat_sym"></a>
<b>B = expmat_sym( A )</b>
<br><b>expmat_sym( B, A )</b>
<ul>
<li>Matrix exponential of symmetric/hermitian matrix <i>A</i></li>
<br>
<li>The computation is based on eigen decomposition</li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the matrix exponential cannot be found:
<ul>
<li><i>B = expmat_sym(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>expmat_sym(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<!--
<br>
<li><b>Caveat</b>: there is no explicit check whether <i>A</i> is symmetric/hermitian</li>
-->
<br>
<li><b>Caveat</b>: the matrix exponential operation is generally <b>not</b> the same as applying the <a href="#misc_fns">exp()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = A*A.t();   // make symmetric matrix

mat C = expmat_sym(B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#expmat">expmat()</a></li>
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="http://en.wikipedia.org/wiki/Matrix_exponential">matrix exponential in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixExponential.html">matrix exponential in MathWorld</a></li>
<li><a href="http://doi.org/10.1137/S00361445024180">Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="find"></a>
<b>find( X )</b>
<br><b>find( X, k )</b>
<br><b>find( X, k, s )</b>
<ul>
<li>Return a column vector containing the indices of elements of <i>X</i> that are non-zero or satisfy a relational condition</li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
</li>
<br>
<li>Relational operators can be used instead of <i>X</i>, eg.&nbsp;<i>A&nbsp;&gt;&nbsp;0.5</i>
</li>
<br>
<li>If <i>k=0</i> (default), return the indices of all non-zero elements, otherwise return at most <i>k</i> of their indices</li>
<br>
<li>If <i>s="first"</i> (default), return at most the first <i>k</i> indices of the non-zero elements
</li>
<br>
<li>If <i>s="last"</i>, return at most the last <i>k</i> indices of the non-zero elements
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>to clamp values to an interval, <a href="#clamp">clamp()</a> is more efficient</li>
<li>to replace a specific value, <a href="#replace">.replace()</a> is more efficient</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);

uvec q1 = find(A &gt; B);
uvec q2 = find(A &gt; 0.5);
uvec q3 = find(A &gt; 0.5, 3, "last");

// change elements of A greater than 0.5 to 1
A.elem( find(A &gt; 0.5) ).ones();
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#all">all()</a></li>
<li><a href="#any">any()</a></li>
<li><a href="#clamp">clamp()</a></li>
<li><a href="#transform">.transform()</a></li>
<li><a href="#approx_equal">approx_equal()</a></li>
<li><a href="#find_finite">find_finite()</a></li>
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
<li><a href="#find_unique">find_unique()</a></li>
<li><a href="#nonzeros">nonzeros()</a></li>
<li><a href="#unique">unique()</a></li>
<li><a href="#sort_index">sort_index()</a></li>
<li><a href="#ind2sub">ind2sub()</a></li>
<li><a href="#index_min_and_index_max_member">.index_min() &amp; .index_max()</a></li>
<li><a href="#trimat_ind">trimatu_ind() / trimatl_ind()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="find_finite"></a>
<b>find_finite( X )</b>
<ul>
<li>Return a column vector containing the indices of elements of <i>X</i> that are finite (ie. not &plusmn;Inf and not NaN)</li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

A(1,1) = datum::inf;

// accumulate only finite elements
double val = accu( A.elem( find_finite(A) ) );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#find">find()</a></li>
<li><a href="#find_nonfinite">find_nonfinite()</a></li>
<li><a href="#is_finite">.is_finite()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#has_inf">.has_inf()</a></li>
<li><a href="#has_nan">.has_nan()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="find_nonfinite"></a>
<b>find_nonfinite( X )</b>
<ul>
<li>Return a column vector containing the indices of elements of <i>X</i> that are non-finite (ie. &plusmn;Inf or NaN)</li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

A(1,1) = datum::inf;
A(2,2) = datum::nan;

// change non-finite elements to zero
A.elem( find_nonfinite(A) ).zeros();
</pre>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> to replace instances of a specific non-finite value (eg. nan or inf),
it is more efficient to use <a href="#replace">.replace()</a>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#find">find()</a></li>
<li><a href="#find_finite">find_finite()</a></li>
<li><a href="#is_finite">.is_finite()</a></li>
<li><a href="#replace">.replace()</a></li>
<li><a href="#has_inf">.has_inf()</a></li>
<li><a href="#has_nan">.has_nan()</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#constants">constants (pi, nan, inf, ...)</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="find_unique"></a>
<b>find_unique( X )</b>
<br><b>find_unique( X, ascending_indices )</b>
<ul>
<li>Return a column vector containing the indices of unique elements of <i>X</i></li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
</li>
<br>
<li>The <i>ascending_indices</i> argument is optional; it is one of:
<ul>
<table>
<tbody>
<tr><td style="text-align: right;"><code>true</code></td><td>&nbsp;=&nbsp;</td><td>the returned indices are sorted to be ascending (<b>default setting</b>)</td></tr>
<tr><td style="text-align: right;"><code>false</code></td><td>&nbsp;=&nbsp;</td><td>the returned indices are in arbitrary order (faster operation)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A = { { 2, 2, 4 }, 
          { 4, 6, 6 } };

uvec indices = find_unique(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#find">find()</a></li>
<li><a href="#unique">unique()</a></li>
<li><a href="#intersect">intersect()</a></li>
<li><a href="#submat">submatrix views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="flip"></a>
<b>fliplr( X )</b>
<br><b>flipud( X )</b>
<ul>
<li>
<i>fliplr():</i> generate a copy of matrix <i>X</i>, with the order of the columns reversed
</li>
<br>
<li>
<i>flipud():</i> generate a copy of matrix <i>X</i>, with the order of the rows reversed
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = fliplr(A);
mat C = flipud(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#reverse">reverse()</a></li>
<li><a href="#shift">shift()</a></li>
<li><a href="#swap_rows">.swap_rows() &amp; .swap_cols()</a></li>
<li><a href="#t_st_members">.t()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="imag_real"></a>
<b>imag( X )</b>
<br><b>real( X )</b>
<ul>
<li>
Extract the imaginary/real part of a complex matrix or cube
</li>
<br>
<li>
Examples:
<ul>
<pre>
cx_mat C(5, 5, fill::randu);

mat    A = imag(C);
mat    B = real(C);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#set_imag">.set_imag()&nbsp;/&nbsp;.set_real()</a></li>
<li><a href="#abs">abs()</a></li>
<li><a href="#conj">conj()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="ind2sub"></a>
<table>
<tbody>
<tr><td>uvec</td><td>&nbsp;sub&nbsp;=&nbsp;<b>ind2sub(&nbsp;size(</b>X<b>),</b>&nbsp;index&nbsp;<b>)</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 1)</td></tr>
<tr><td>umat</td><td>&nbsp;sub&nbsp;=&nbsp;<b>ind2sub(&nbsp;size(</b>X<b>),</b>&nbsp;vector_of_indices&nbsp;<b>)</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 2)</td></tr>
</tbody>
</table>
<ul>
<li>
Convert a linear index, or a vector of indices, to subscript notation
</li>
<br>
<li>
The argument <i><b>size(</b>X<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b>&nbsp;n_cols<b>)</b></i> or <i><b>size(</b>n_rows<b>,</b>&nbsp;n_cols<b>,</b>&nbsp;n_slices<b>)</b></i>
</li>
<br>
<li>
A&nbsp;<i>std::logic_error</i> exception is thrown if an index is out of range
</li>
<br>
<li>
When only one index is given (form 1), the subscripts are returned in a vector of type <a href="#Col">uvec</a>
</li>
<br>
<li>
When a vector of indices (of type <a href="#Col">uvec</a>) is given (form 2), the corresponding subscripts are returned in each column of an <i>m&nbsp;x&nbsp;n</i> matrix of type <a href="#Mat">umat</a>;
<i>m=2</i> for matrix subscripts, while <i>m=3</i> for cube subscripts
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat M(4, 5, fill::randu);

uvec s = ind2sub( size(M), 6 );

cout &lt;&lt; "row: " &lt;&lt; s(0) &lt;&lt; endl;
cout &lt;&lt; "col: " &lt;&lt; s(1) &lt;&lt; endl;


uvec indices = find(M &gt; 0.5);
umat t       = ind2sub( size(M), indices );


cube Q(2,3,4);

uvec u = ind2sub( size(Q), 8 );

cout &lt;&lt; "row:   " &lt;&lt; u(0) &lt;&lt; endl;
cout &lt;&lt; "col:   " &lt;&lt; u(1) &lt;&lt; endl;
cout &lt;&lt; "slice: " &lt;&lt; u(2) &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#size">size()</a></li>
<li><a href="#sub2ind">sub2ind()</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#find">find()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="index_min_and_index_max_standalone"></a>
<table>
<tbody>
<tr>
<td>
<b>index_min( V )</b>
<br><b>index_min( M )</b>
<br><b>index_min( M, dim )</b>
<br><b>index_min( Q )</b>
<br><b>index_min( Q, dim )</b>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
<b>index_max( V )</b>
<br><b>index_max( M )</b>
<br><b>index_max( M, dim )</b>
<br><b>index_max( Q )</b>
<br><b>index_max( Q, dim )</b>
</td>
</tr>
</tbody>
</table>
<ul>
<li>
For vector <i>V</i>, return the linear index of the extremum value; the returned index is of type <a href="#uword">uword</a>
</li>
<br>
<li>
For matrix <i>M</i> and:
<ul>
<li>
<i>dim=0</i>, return a row vector (of type <a href="#Row">urowvec</a> or <a href="#Mat">umat</a>), 
with each column containing the index of the extremum value in the corresponding column of <i>M</i>
</li>
<li>
<i>dim=1</i>, return a column vector (of type <a href="#Col">uvec</a> or <a href="#Mat">umat</a>),
with each row containing the index of the extremum value in the corresponding row of <i>M</i>
</li>
</ul>
</li>
<br>
<li>
For cube <i>Q</i>, return a cube (of type <a href="#Cube">ucube</a>) containing the indices of extremum values of elements along dimension <i>dim</i>, where <i>dim</i> &isin; {&nbsp;0,&nbsp;1,&nbsp;2&nbsp;}
</li>
<br>
<li>
For each column, row, or slice, the index starts at zero
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For objects with complex numbers, absolute values are used for comparison
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec v(10, fill::randu);

uword i = index_max(v);
double max_val_in_v = v(i);


mat M(5, 6, fill::randu);

urowvec ii = index_max(M);
ucolvec jj = index_max(M,1);

double max_val_in_col_2 = M( ii(2), 2 );

double max_val_in_row_4 = M( 4, jj(4) );
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#min_and_max">min() &amp; max()</a></li>
<li><a href="#index_min_and_index_max_member">.index_min() &amp; .index_max()</a> (member functions)</li>
<li><a href="#sort_index">sort_index()</a></li>
<li><a href="#find">find()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="inplace_trans"></a>
<b>inplace_trans( X )
<br>inplace_trans( X, method )
<br>
<br>inplace_strans( X )
<br>inplace_strans( X, method )
</b>
<ul>
<li>
In-place / in-situ transpose of matrix <i>X</i>
</li>
<br>
<li>
For real (non-complex) matrix:
<ul>
<li><i>inplace_trans()</i> performs a normal transpose</li>
<li><i>inplace_strans()</i> not applicable</li>
</ul>
</li>
<br>
<li>
For complex matrix:
<ul>
<li><i>inplace_trans()</i> performs a Hermitian transpose (ie. the conjugate of the elements is taken during the transpose)</li>
<li><i>inplace_strans()</i> provides a transposed copy without taking the conjugate of the elements</li>
</ul>
</li>
<br>
<li>
The argument <i>method</i> is optional
</li>
<br>
<li>
By default, a greedy transposition algorithm is used; a low-memory algorithm can be used instead by explicitly setting <i>method</i> to <code>"lowmem"</code>
</li>
<br>
<li>
The low-memory algorithm is considerably slower than the greedy algorithm;
using the low-memory algorithm is only recommended for cases where <i>X</i> takes up more than half of available memory (ie. very large <i>X</i>)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4,     5,     fill::randu);
mat Y(20000, 30000, fill::randu);

inplace_trans(X);            // use greedy algorithm by default

inplace_trans(Y, "lowmem");  // use low-memory (and slow) algorithm
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#t_st_members">.t()</a></li>
<li><a href="#trans">trans()</a></li>
<li><a href="https://en.wikipedia.org/wiki/In-place_matrix_transposition">inplace matrix transpose in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="intersect"></a>
<table>
<tbody>
<tr><td><b>C = intersect( A, B )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 1)</td></tr>
<tr><td><b>intersect( C, iA, iB, A, B )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 2)</td></tr>
</tbody>
</table>
<ul>
<li>
For form 1:
<ul>
<li>return the unique elements common to both <i>A</i> and <i>B</i>, sorted in ascending order</li>
</ul>
</li>
<br>
<li>
For form 2:
<ul>
<li>store in <i>C</i> the unique elements common to both <i>A</i> and <i>B</i>, sorted in ascending order</li>
<li>store in <i>iA</i> and <i>iB</i> the indices of the unique elements, such that <i>C = A.elem(iA)</i> and <i>C = B.elem(iB)</i></li>
<li><i>iA</i> and <i>iB</i> must have the type <a href="#Col">uvec</a> (ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)</li>
</ul>
</li>
<br>
<li>
<i>C</i> is a column vector if either <i>A</i> or <i>B</i> is a matrix or column vector;
<i>C</i> is a row vector if both <i>A</i> and <i>B</i> are row vectors
</li>
<br>
<li>
For matrices and vectors with complex numbers, ordering is via absolute values 
</li>
<br>
<li>
Examples:
<ul>
<pre>
ivec A = regspace&lt;ivec&gt;(4, 1);  // 4, 3, 2, 1
ivec B = regspace&lt;ivec&gt;(3, 6);  // 3, 4, 5, 6

ivec C = intersect(A,B);       // 3, 4

ivec CC;
uvec iA;
uvec iB;

intersect(CC, iA, iB, A, B);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#unique">unique()</a></li>
<li><a href="#find_unique">find_unique()</a></li>
<li><a href="#submat">submatrix views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="join"></a>
<table>
<tbody>
<tr>
<td>
<b>join_rows( A, B )</b>
<br><b>join_rows( A, B, C )</b>
<br><b>join_rows( A, B, C, D )</b>
<br>&nbsp;
<br><b>join_cols( A, B )</b>
<br><b>join_cols( A, B, C )</b>
<br><b>join_cols( A, B, C, D )</b>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
<b>join_horiz( A, B )</b>
<br><b>join_horiz( A, B, C )</b>
<br><b>join_horiz( A, B, C, D )</b>
<br>&nbsp;
<br><b>join_vert( A, B )</b>
<br><b>join_vert( A, B, C )</b>
<br><b>join_vert( A, B, C, D )</b>
</td>
</tr>
</tbody>
</table>
<ul>
<li>
<i>join_rows()</i> and <i>join_horiz()</i>: horizontal concatenation;
join the corresponding rows of the given matrices;
the given matrices must have the same number of rows
</li>
<br>
<li>
<i>join_cols()</i> and <i>join_vert()</i>: vertical concatenation;
join the corresponding columns of the given matrices;
the given matrices must have the same number of columns
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B(4, 6, fill::randu);
mat C(6, 5, fill::randu);

mat AB = join_rows(A,B);
mat AC = join_cols(A,C);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#shed">.shed_rows/cols/slices</a></li>
<li><a href="#insert">.insert_rows/cols/slices</a></li>
<li><a href="#submat">submatrix views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="join_slices"></a>
<b>join_slices( cube C, cube D )</b>
<br><b>join_slices( mat  M, mat  N )</b>
<br>
<br><b>join_slices( mat  M, cube C )</b>
<br><b>join_slices( cube C, mat  M )</b>
<ul>
<li>
for two cubes <i>C</i> and <i>D</i>: join the slices of <i>C</i> with the slices of <i>D</i>;
cubes <i>C</i> and <i>D</i> must have the same number of rows and columns (ie. all slices must have the same size)
</li>
<br>
<li>
for two matrices <i>M</i> and <i>N</i>: treat <i>M</i> and <i>N</i> as cube slices and join them to form a cube with 2 slices;
matrices <i>M</i> and <i>N</i> must have the same number of rows and columns
</li>
<br>
<li>
for matrix <i>M</i> and cube <i>C</i>: treat <i>M</i> as a cube slice and join it with the slices of <i>C</i>;
matrix <i>M</i> and cube <i>C</i> must have the same number of rows and columns
</li>
<br>
<li>
Examples:
<ul>
<pre>
cube C(5, 10, 3, fill::randu);
cube D(5, 10, 4, fill::randu);

cube E = join_slices(C,D);

mat M(10, 20, fill::randu);
mat N(10, 20, fill::randu);

cube Q = join_slices(M,N);

cube R = join_slices(Q,M);

cube S = join_slices(M,Q);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#shed">.shed_rows/cols/slices</a></li>
<li><a href="#insert">.insert_rows/cols/slices</a></li>
<li><a href="#subcube">subcube views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="kron"></a>
<b>kron( A, B )</b>

<ul>
<li>Kronecker tensor product</li>
<br>
<li>Given matrix <i>A</i> (with <i>n</i> rows and <i>p</i> columns) and matrix <i>B</i> (with <i>m</i> rows and <i>q</i> columns),
generate a matrix (with <i>nm</i> rows and <i>pq</i> columns) that denotes the tensor product of <i>A</i> and <i>B</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B(5, 4, fill::randu);

mat K = kron(A,B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#repmat">repmat()</a></li>
<li><a href="#repelem">repelem()</a></li>
<li><a href="http://mathworld.wolfram.com/KroneckerProduct.html">Kronecker product in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Kronecker_product">Kronecker product in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="log_det"></a>
<table>
<tbody>
<tr><td><b>log_det( val, sign, A )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 1)</td></tr>
<tr><td><b>complex result = log_det( A )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 2)</td></tr>
</tbody>
</table>
<ul>
<li>
Log determinant of square matrix <i>A</i>
</li>
<br>
<li>
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>form 1: store the calculated log determinant in <i>val</i> and <i>sign</i>
<br>the determinant is equal to <i>exp(val)*sign</i>
</li>
<br>
<li>form 2: return the complex log determinant
<ul>
<li>
if matrix <i>A</i> is real and the determinant is positive:
<ul>
<li>the real part of the result is the log determinant</li>
<li>the imaginary part is zero</li>
</ul>
</li>
<li>
if matrix <i>A</i> is real and the determinant is negative:
<ul>
<li>the real part of the result is the log of the absolute value of the determinant</li>
<li>the imaginary part is equal to <i><a href="#constants">datum::pi</a></i></li>
</ul>
</li>
</ul>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double val;
double sign;

log_det(val, sign, A);          // form 1

cx_double result = log_det(A);  // form 2
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#det">det()</a></li>
<li><a href="#rcond">rcond()</a></li>
<li><a href="#cx_double">cx_double</a></li>
<li><a href="http://mathworld.wolfram.com/Determinant.html">determinant in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Determinant">determinant in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="logmat"></a>
<b>B = logmat( A )</b>
<br><b>logmat( B, A )</b>
<ul>
<li>Complex matrix logarithm of general square matrix <i>A</i></li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the matrix logarithm cannot be found:
<ul>
<li><i>B = logmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>logmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li><b>Caveat</b>: if matrix <i>A</i> is symmetric positive definite, using <a href="#logmat_sympd">logmat_sympd()</a> is faster</li>
<br>
<li><b>Caveat</b>: the matrix logarithm operation is generally <b>not</b> the same as applying the <a href="#misc_fns">log()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
   mat A(5, 5, fill::randu);

cx_mat B = logmat(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
<li><a href="#expmat">expmat()</a></li>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#imag_real">real()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="https://en.wikipedia.org/wiki/Logarithm_of_a_matrix">matrix logarithm in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="logmat_sympd"></a>
<b>B = logmat_sympd( A )</b>
<br><b>logmat_sympd( B, A )</b>
<ul>
<li>Matrix logarithm of symmetric/hermitian positive definite matrix <i>A</i></li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the matrix logarithm cannot be found:
<ul>
<li><i>B = logmat_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>logmat_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<!--
<br>
<li><b>Caveat</b>: there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
-->
<br>
<li><b>Caveat</b>: the matrix logarithm operation is generally <b>not</b> the same as applying the <a href="#misc_fns">log()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = A*A.t();   // make symmetric matrix

mat C = logmat_sympd(B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#logmat">logmat()</a></li>
<li><a href="#expmat_sym">expmat_sym()</a></li>
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="https://en.wikipedia.org/wiki/Logarithm_of_a_matrix">matrix logarithm in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="min_and_max"></a>
<table>
<tbody>
<tr>
<td>
<b>min( V )</b>
<br><b>min( M )</b>
<br><b>min( M, dim )</b>
<br><b>min( Q )</b>
<br><b>min( Q, dim )</b>
<br><b>min( A, B )</b>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td>
<b>max( V )</b>
<br><b>max( M )</b>
<br><b>max( M, dim )</b>
<br><b>max( Q )</b>
<br><b>max( Q, dim )</b>
<br><b>max( A, B )</b>
</td>
</tr>
</tbody>
</table>
<ul>
<li>
For vector <i>V</i>, return the extremum value
</li>
<br>
<li>
For matrix <i>M</i>, return the extremum value for each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
For cube <i>Q</i>, return the extremum values of elements along dimension <i>dim</i>, where <i>dim</i> &isin; {&nbsp;0,&nbsp;1,&nbsp;2&nbsp;}
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For two matrices/cubes <i>A</i> and <i>B</i>, return a matrix/cube containing element-wise extremum values
</li>
<br>
<li>
For objects with complex numbers, absolute values are used for comparison
</li>
<br>
<li>
Examples:
<ul>
<pre>
colvec v(10, fill::randu);
double x = max(v);

mat M(10, 10, fill::randu);

rowvec a = max(M);
rowvec b = max(M,0); 
colvec c = max(M,1);

// element-wise maximum
mat X(5, 6, fill::randu);
mat Y(5, 6, fill::randu);
mat Z = arma::max(X,Y);  // use arma:: prefix to distinguish from std::max()
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#min_and_max_member">.min() &amp; .max()</a> (member functions)</li>
<li><a href="#index_min_and_index_max_standalone">index_min() &amp; index_max()</a>
<li><a href="#clamp">clamp()</a>
<li><a href="#stats_fns">statistics functions</a>
<li><a href="#running_stat">running_stat</a> - class for running statistics of scalars</li>
<li><a href="#running_stat_vec">running_stat_vec</a> - class for running statistics of vectors</li>
<li><a href="http://ensmallen.org">ensmallen</a> - library for finding minimum of arbitrary function</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="nonzeros"></a>
<b>nonzeros( X )</b>
<ul>
<li>
Return a column vector containing the non-zero values of <i>X</i>
</li>
<br>
<li>
<i>X</i> can be a sparse or dense matrix
</li>
<br>
<li>
<b>Caveat:</b> do not use <i>nonzeros()</i> if you only want to obtain the number of non-zero elements in a sparse matrix;
use the <i>.n_nonzero</i> <a href="#attributes">attribute</a> instead, eg.&nbsp;<i>X.n_nonzero</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = sprandu&lt;sp_mat&gt;(100, 100, 0.1);
   vec a = nonzeros(A);

mat B(100, 100, fill::eye);
vec b = nonzeros(B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#find">find()</a>
<li><a href="#unique">unique()</a></li>
<li><a href="#vectorise">vectorise()</a>
<li><a href="#for_each">.for_each()</a>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="norm"></a>
<b>norm( X )</b>
<br><b>norm( X, p )</b>
<ul>
<li>
Compute the <i>p</i>-norm of <i>X</i>, where <i>X</i> can be a vector or matrix
</li>
<br>
<li>
For vectors, <i>p</i> is an integer &ge;1, or one of: <code>"-inf"</code>, <code>"inf"</code>, <code>"fro"</code>
</li>
<br>
<li>
For matrices, <i>p</i> is one of: 1, 2, <code>"inf"</code>, <code>"fro"</code>; the calculated norm is the <i>induced norm</i> (not entrywise norm)
</li>
<br>
<li>
<code>"-inf"</code> is the minimum norm, <code>"inf"</code> is the maximum norm, while <code>"fro"</code> is the Frobenius norm
</li>
<br>
<li>
The argument <i>p</i> is optional; by default <i>p=2</i> is used
</li>
<br>
<li>
For vector norm with <i>p=2</i> and matrix norm with <i>p="fro"</i>, a robust algorithm is used to reduce the likelihood of underflows and overflows
</li>
<br>
<li>
To obtain the zero norm or Hamming norm (ie. the number of non-zero elements),
use this expression: <code><a href="#accu">accu</a>(X&nbsp;!=&nbsp;0)</code>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec q(5, fill::randu);

double x = norm(q, 2);
double y = norm(q, "inf");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#normalise">normalise()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#dot">dot()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Norm_(mathematics)">vector norm in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/VectorNorm.html">vector norm in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Matrix_norm">matrix norm in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixNorm.html">matrix norm in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="normalise"></a>
<b>normalise( V )</b>
<br><b>normalise( V, p )</b>
<br>
<br><b>normalise( X )</b>
<br><b>normalise( X, p )</b>
<br><b>normalise( X, p, dim )</b>
<ul>
<li>For vector <i>V</i>, return its normalised version (ie. having unit <i>p</i>-norm)</li>
<br>
<li>
For matrix <i>X</i>, return its normalised version, where each column (<i>dim=0</i>) or row (<i>dim=1</i>) has been normalised to have unit <i>p</i>-norm</li>
<br>
<li>
The <i>p</i> argument is optional; by default <i>p=2</i> is used
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec A(10, fill::randu);
vec B = normalise(A);
vec C = normalise(A, 1);

mat X(5, 6, fill::randu);
mat Y = normalise(X);
mat Z = normalise(X, 2, 1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#norm">norm()</a></li>
<li><a href="#dot">norm_dot()</a></li>
<li><a href="http://mathworld.wolfram.com/NormalizedVector.html">Normalised vector in MathWorld</a>
<li><a href="http://en.wikipedia.org/wiki/Unit_vector">Unit vector in Wikipedia</a>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="prod"></a>
<b>prod( V )</b>
<br><b>prod( M )</b>
<br><b>prod( M, dim )</b>
<ul>
<li>
For vector <i>V</i>, return the product of all elements
</li>
<br>
<li>
For matrix <i>M</i>, return the product of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
colvec v(10, fill::randu);
double x = prod(v);

mat M(10, 10, fill::randu);

rowvec a = prod(M);
rowvec b = prod(M,0);
colvec c = prod(M,1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cumprod">cumprod()</a></li>
<li><a href="#schur_product">Schur product</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="powmat"></a>
<b>B = powmat( A, n )</b>
<br><b>powmat( B, A, n )</b>
<ul>
<li>Matrix power operation: raise square matrix <i>A</i> to the power of <i>n</i>, where <i>n</i> has the type <i>int</i> or <i>double</i></li>
<br>
<li>If <i>n</i> has the type <i>double</i>, the resultant matrix <i>B</i> always has complex elements</li>
<br>
<li>For <i>n&nbsp;=&nbsp;0</i>, an identity matrix is generated</li>
<br>
<!--
<li>For <i>n&nbsp;&leq;&nbsp;-1</i>, inverse of <i>A</i> is raised to the power of <i>abs(n)</i></li>
<br>
-->
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the matrix power cannot be found:
<ul>
<li><i>B = powmat(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>powmat(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li><b>Caveats</b>:
<ul>
<li>to find the inverse of a matrix, use <a href="#inv">inv()</a> instead</li>
<li>to solve a system of linear equations, use <a href="#solve">solve()</a> instead</li>
<li>to find the matrix square root, use <a href="#sqrtmat">sqrtmat()</a> instead</li>
<li>the matrix power operation is generally <b>not</b> the same as applying the <a href="#misc_fns">pow()</a> function to each element</li>
</ul>
<br>
<li>
Examples:
<ul>
<pre>
   mat A(5, 5, fill::randu);

   mat B = powmat(A, 4);     //     integer exponent

cx_mat C = powmat(A, 4.56);  // non-integer exponent
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#inv">inv()</a></li>
<li><a href="#eye_standalone">eye()</a></li>
<li><a href="#operators">operators</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="rank"></a>
<b>rank( X )</b>
<br>
<b>rank( X, tolerance )</b>
<ul>
<li>Return the rank of matrix <i>X</i></li>
<br>
<li>Any singular values less than <i>tolerance</i> are treated as zero</li>
<br>
<li>
The <i>tolerance</i> argument is optional; by default <i>tolerance</i> is <i>max(m,n)*max_sv*datum::eps</i>, where:
<ul>
<li><i>m</i> = number of rows and <i>n</i> = number of columns in <i>X</i></li>
<li><i>max_sv</i> = maximal singular value of <i>X</i></li>
<li><i>datum::eps</i> = difference between 1 and the least value greater than 1 that is representable</li>
</ul>
</li>
<br>
<li>The computation is based on singular value decomposition;
if the decomposition fails, a <i>std::runtime_error</i> exception is thrown</li>
<br>
<li>
<b>Caveat:</b> to confirm whether a matrix is singular, use <a href="#rcond">rcond()</a> or <a href="#cond">cond()</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

uword r = rank(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cond">cond()</a></li>
<li><a href="#rcond">rcond()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#orth">orth()</a></li>
<li><a href="#constants">datum::eps</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixRank.html">Rank in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Rank_(linear_algebra)">Rank in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="rcond"></a>
<b>rcond( A )</b>
<ul>
<li>
Return the 1-norm estimate of the reciprocal of the condition number of square matrix <i>A</i>
</li>
<br>
<li>
Values close to 1 suggest that <i>A</i> is well-conditioned
</li>
<br>
<li>
Values close to 0 suggest that <i>A</i> is badly conditioned
</li>
<br>
<li>
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double r = rcond(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cond">cond()</a></li>
<li><a href="#rank">rank()</a></li>
<li><a href="#det">det()</a></li>
<li><a href="#inv">inv()</a></li>
<li><a href="#solve">solve()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="repelem"></a>
<b>repelem( A, num_copies_per_row, num_copies_per_col )</b>
<ul>
<li>Generate a matrix by replicating each element of matrix <i>A</i></li>
<br>
<li>The generated matrix has the following size:
<ul>
<table border="0">
<tbody>
<tr><td>n_rows</td><td>&nbsp;=&nbsp;</td><td>num_copies_per_row</td><td>*</td><td>A.n_rows</td></tr>
<tr><td>n_cols</td><td>&nbsp;=&nbsp;</td><td>num_copies_per_col</td><td>*</td><td>A.n_cols</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(2, 3, fill::randu);

mat B = repelem(A, 4, 5);
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#repmat">repmat()</a></li>
<li><a href="#kron">kron()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#resize">resize()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="repmat"></a>
<b>repmat( A, num_copies_per_row, num_copies_per_col )</b>
<ul>
<li>Generate a matrix by replicating matrix <i>A</i> in a block-like fashion</li>
<br>
<li>The generated matrix has the following size:
<ul>
<table border="0">
<tbody>
<tr><td>n_rows</td><td>&nbsp;=&nbsp;</td><td>num_copies_per_row</td><td>*</td><td>A.n_rows</td></tr>
<tr><td>n_cols</td><td>&nbsp;=&nbsp;</td><td>num_copies_per_col</td><td>*</td><td>A.n_cols</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> to apply a vector operation on each row or column of a matrix,
it is generally more efficient to use <a href="#each_colrow">.each_row()</a> or <a href="#each_colrow">.each_col()</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(2, 3, fill::randu);

mat B = repmat(A, 4, 5);
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="#each_colrow">.each_col() &amp; .each_row()</a> &nbsp; (vector operations applied to each column or row)</li>
<li><a href="#repelem">repelem()</a></li>
<li><a href="#kron">kron()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#resize">resize()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="reshape"></a>
<b>reshape( X, n_rows, n_cols )</b> &nbsp;&nbsp; (X is a vector or matrix)
<br><b>reshape( X, size(Y) )</b>
<br>
<br><b>reshape( Q, n_rows, n_cols, n_slices )</b> &nbsp;&nbsp; (Q is a cube)
<br><b>reshape( Q, size(R) )</b>
<ul>
<li>
Generate a vector/matrix/cube with given size specifications,
whose elements are taken from the given object in a column-wise manner;
the elements in the generated object are placed column-wise (ie. the first column is filled up before filling the second column)
</li>
<br>
<li>
The layout of the elements in the generated object will be different to the layout in the given object
</li>
<br>
<li>
If the total number of elements in the given object is less than the specified size,
the remaining elements in the generated object are set to zero
</li>
<br>
<li>
If the total number of elements in the given object is greater than the specified size,
only a subset of elements is taken from the given object
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>
do not use <i>reshape()</i> if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<li>
to grow/shrink a matrix while preserving the elements <b>as well as</b> the layout of the elements,
use <a href="#resize">resize()</a> instead
</li>
<li>
to flatten a matrix into a vector, use <a href="#vectorise">vectorise()</a> or <a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a> instead
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 5, fill::randu);

mat B = reshape(A, 5, 10);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#reshape_member">.reshape()</a> (member function)</li>
<li><a href="#set_size">.set_size()</a></li>
<li><a href="#resize">resize()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#repmat">repmat()</a></li>
<li><a href="#repelem">repelem()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="#interp2">interp2()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="resize"></a>
<b>resize( X, n_rows, n_cols )</b> &nbsp;&nbsp; (X is a vector or matrix)
<br><b>resize( X, size(Y) )</b>
<br>
<br><b>resize( Q, n_rows, n_cols, n_slices )</b> &nbsp;&nbsp; (Q is a cube)
<br><b>resize( Q, size(R) )</b>
<ul>
<li>
Generate a vector/matrix/cube with given size specifications,
whose elements as well as the layout of the elements are taken from the given object
</li>
<br>
<li>
<b>Caveat:</b>
do not use <i>resize()</i> if you simply want to change the size without preserving data;
use <a href="#set_size">.set_size()</a> instead, which is much faster
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

mat B = resize(A, 7, 6);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#resize_member">.resize()</a> (member function of Mat and Cube)</li>
<li><a href="#set_size">.set_size()</a> (member function of Mat and Cube)</li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#vectorise">vectorise()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#conv_to">conv_to()</a></li>
<li><a href="#repmat">repmat()</a></li>
<li><a href="#repelem">repelem()</a></li>
<li><a href="#size">size()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="reverse"></a>
<b>reverse( V )</b>
<br><b>reverse( X )</b>
<br><b>reverse( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, generate a copy of the vector with the order of elements reversed
</li>
<br>
<li>
For matrix <i>X</i>, generate a copy of the matrix with the order of elements reversed in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec v(123, fill::randu);
vec y = reverse(v);

mat A(4, 5, fill::randu);
mat B = reverse(A);
mat C = reverse(A,1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#flip">fliplr() &amp; flipud()</a></li>
<li><a href="#shift">shift()</a></li>
<li><a href="#sort">sort()</a></li>
<li><a href="#swap_rows">.swap_rows() &amp; .swap_cols()</a></li>
<li><a href="#t_st_members">.t()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="roots"></a>
<b>R = roots( P )</b>
<br><b>roots( R, P )</b>
<ul>
<li>
Find the complex roots of a polynomial function represented via vector <i>P</i> and store them in column vector <i>R</i>
</li>
<br>
<li>
The polynomial function is modelled as:
<ul>
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
  + p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
  + p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
  + ...
  + p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
  + p<sub><sub>N</sub></sub>
</ul>
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient in vector <i>P</i>
</li>
<br>
<li>The computation is based on eigen decomposition; if the decomposition fails:
<ul>
<li><i>R = roots(P)</i> resets <i>R</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>roots(R,P)</i> resets <i>R</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
   vec P(5, fill::randu);
  
cx_vec R = roots(P);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#polyval">polyval()</a></li>
<li><a href="#polyfit">polyfit()</a></li>
<li><a href="#imag_real">real()</a></li>
<li><a href="#solve">solve()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Zero_of_a_function">zero of a function in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="shift"></a>
<b>shift( V, N )</b>
<br><b>shift( X, N )</b>
<br><b>shift( X, N, dim )</b>
<ul>
<li>
For vector <i>V</i>, generate a copy of the vector with the elements shifted by <i>N</i> positions in a circular manner
</li>
<br>
<li>
For matrix <i>X</i>, generate a copy of the matrix with the elements shifted by <i>N</i> positions in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
<i>N</i> can be positive or negative
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B = shift(A, -1);
mat C = shift(A, +1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#shuffle">shuffle()</a></li>
<li><a href="#flip">fliplr() &amp; flipud()</a></li>
<li><a href="#reverse">reverse()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="shuffle"></a>
<b>shuffle( V )</b>
<br><b>shuffle( X )</b>
<br><b>shuffle( X, dim )</b>
<ul>
<li>
For vector <i>V</i>, generate a copy of the vector with the elements shuffled
</li>
<br>
<li>
For matrix <i>X</i>, generate a copy of the matrix with the elements shuffled in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);
mat B = shuffle(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#shift">shift()</a></li>
<li><a href="#sort">sort()</a></li>
<li><a href="#unique">unique()</a></li>
<li><a href="#randu_randn_standalone">randu() / randn()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="size"></a>
<b>size(&nbsp;X&nbsp;)</b>
<br>
<b>size(&nbsp;n_rows,&nbsp;n_cols&nbsp;)</b>
<br>
<b>size(&nbsp;n_rows,&nbsp;n_cols,&nbsp;n_slices&nbsp;)</b>
<ul>
<li>
Obtain the dimensions of object <i>X</i>, or explicitly specify the dimensions
</li>
<br>
<li>
The dimensions can be used in conjunction with:
<ul>
<li><a href="#part_a">object constructors</a></li>
<li><a href="#part_b">functions for changing size</a></li>
<li><a href="#part_c">generator functions</a></li>
<li><a href="#submat">submatrix views</a></li>
<li><a href="#subcube">subcube views</a></li>
<li><a href="#subfield">subfield views</a></li>
<li><a href="#ind2sub">ind2sub()</a> and <a href="#sub2ind">sub2ind()</a></li>
</ul>
</li>
<br>
<li>
The dimensions support simple arithmetic operations; they can also be printed and compared for equality/inequality
</li>
<br>
<li>
<b>Caveat:</b> to prevent interference from <a href="https://en.cppreference.com/w/cpp/iterator/size"><i>std::size()</i></a> in C++17,
preface Armadillo's <i>size()</i> with the <i>arma</i> namespace qualification, eg. <i>arma::size(X)</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5,6);

mat B(size(A), fill::zeros);

mat C; C.randu(size(A));

mat D = ones&lt;mat&gt;(size(A));

mat E(10,20, fill::ones);
E(3,4,size(C)) = C;    // access submatrix of E

mat F( size(A) + size(E) );

mat G( size(A) * 2 );

cout &lt;&lt; "size of A: " &lt;&lt; size(A) &lt;&lt; endl;

bool is_same_size = (size(A) == size(E));
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#attributes">attributes</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sort"></a>
<b>sort( V )</b>
<br><b>sort( V, sort_direction )</b>
<br>
<br><b>sort( X )</b>
<br><b>sort( X, sort_direction )</b>
<br><b>sort( X, sort_direction, dim )</b>
<br>
<ul>
<li>For vector <i>V</i>, return a vector which is a sorted version of the input vector</li>
<br>
<li>For matrix <i>X</i>, return a matrix with the elements of the input matrix sorted in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is either <code>"ascend"</code> or <code>"descend"</code>; by default <code>"ascend"</code> is used</li>
<br>
<li>For matrices and vectors with complex numbers, sorting is via absolute values</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 10, fill::randu);
mat B = sort(A);
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#sort_index">sort_index()</a></li>
<li><a href="#is_sorted">.is_sorted()</a></li>
<li><a href="#shuffle">shuffle()</a></li>
<li><a href="#unique">unique()</a></li>
<li><a href="#reverse">reverse()</a></li>
<li><a href="#randu_randn_standalone">randu() / randn()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sort_index"></a>
<b>sort_index( X )</b>
<br><b>sort_index( X, sort_direction )</b>
<br>
<br><b>stable_sort_index( X )</b>
<br><b>stable_sort_index( X, sort_direction )</b>
<ul>
<li>Return a vector which describes the sorted order of the elements of <i>X</i>
(ie. it contains the indices of the elements of <i>X</i>)
</li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
<i>X</i> is interpreted as a vector, with column-by-column ordering of the elements of <i>X</i>
</li>
<br>
<li>The <i>sort_direction</i> argument is optional; <i>sort_direction</i> is either <code>"ascend"</code> or <code>"descend"</code>; by default <code>"ascend"</code> is used</li>
<br>
<li>The <i>stable_sort_index()</i> variant preserves the relative order of elements with equivalent values</li>
<br>
<li>For matrices and vectors with complex numbers, sorting is via absolute values</li>
<br>
<li>
Examples:
<ul>
<pre>
vec q(10, fill::randu);

uvec indices = sort_index(q);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sort">sort()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#is_sorted">.is_sorted()</a></li>
<li><a href="#index_min_and_index_max_member">.index_min() &amp; .index_max()</a></li>
<li><a href="#ind2sub">ind2sub()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sqrtmat"></a>
<b>B = sqrtmat( A )</b>
<br><b>sqrtmat( B, A )</b>
<ul>
<li>Complex square root of general square matrix <i>A</i></li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>
If matrix <i>A</i> appears to be singular, an approximate square root is attempted; additionally, <i>sqrtmat(B,A)</i> returns a bool set to false
</li>
<br>
<li><b>Caveat</b>: if matrix <i>A</i> is symmetric positive definite, using <a href="#sqrtmat_sympd">sqrtmat_sympd()</a> is faster</li>
<br>
<li><b>Caveat</b>: the square root of a matrix is generally <b>not</b> the same as applying the <a href="#misc_fns">sqrt()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
   mat A(5, 5, fill::randu);

cx_mat B = sqrtmat(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
<li><a href="#powmat">powmat()</a></li>
<li><a href="#expmat">expmat()</a></li>
<li><a href="#logmat">logmat()</a></li>
<li><a href="#chol">chol()</a></li>
<li><a href="#imag_real">real()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="https://en.wikipedia.org/wiki/Square_root_of_a_matrix">square root of a matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sqrtmat_sympd"></a>
<b>B = sqrtmat_sympd( A )</b>
<br><b>sqrtmat_sympd( B, A )</b>
<ul>
<li>Square root of symmetric/hermitian positive definite matrix <i>A</i></li>
<br>
<li>If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the square root cannot be found:
<ul>
<li><i>B = sqrtmat_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>sqrtmat_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<!--
<br>
<li><b>Caveat</b>: there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
-->
<br>
<li><b>Caveat</b>: the matrix square root operation is generally <b>not</b> the same as applying the <a href="#misc_fns">sqrt()</a> function to each element</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = A*A.t();   // make symmetric matrix

mat C = sqrtmat_sympd(B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#expmat_sym">expmat_sym()</a></li>
<li><a href="#logmat_sympd">logmat_sympd()</a></li>
<li><a href="#chol">chol()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="https://en.wikipedia.org/wiki/Square_root_of_a_matrix">square root of a matrix in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sum"></a>
<b>sum( V )</b>
<br><b>sum( M )</b>
<br><b>sum( M, dim )</b>
<br><b>sum( Q )</b>
<br><b>sum( Q, dim )</b>
<ul>
<li>
For vector <i>V</i>, return the sum of all elements
</li>
<br>
<li>
For matrix <i>M</i>, return the sum of elements in each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
For cube <i>Q</i>, return the sums of elements along dimension <i>dim</i>, where <i>dim</i> &isin; {&nbsp;0,&nbsp;1,&nbsp;2&nbsp;};
for example, <i>dim=0</i> indicates the sum of elements in each column within each slice
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
<b>Caveat:</b> to get a sum of all the elements regardless of the object type (ie. vector, or matrix, or cube), use <a href="#accu">accu()</a> instead
</li>
<br>
<li>
Examples:
<ul>
<pre>
colvec v(10, fill::randu);
double x = sum(v);

mat M(10, 10, fill::randu);

rowvec a = sum(M);
rowvec b = sum(M,0);
colvec c = sum(M,1);

double y = accu(M);   // find the overall sum regardless of object type
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#accu">accu()</a></li>
<li><a href="#cumsum">cumsum()</a></li>
<li><a href="#trace">trace()</a></li>
<li><a href="#trapz">trapz()</a></li>
<li><a href="#stats_fns">mean()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="sub2ind"></a>
<table>
<tbody>
<tr><td>uword&nbsp;</td><td>index</td><td>&nbsp;=&nbsp;<b>sub2ind(&nbsp;size(</b>M<b>),</b>&nbsp;row<b>,</b>&nbsp;col&nbsp;<b>)</b></td><td>(<i>M</i> is a matrix)</td></tr>
<tr><td>uvec&nbsp;</td><td>indices</td><td>&nbsp;=&nbsp;<b>sub2ind(&nbsp;size(</b>M<b>),</b>&nbsp;matrix_of_subscripts&nbsp;<b>)</b></td><td></td></tr>
<tr><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr>
<tr><td>uword&nbsp;</td><td>index</td><td>&nbsp;=&nbsp;<b>sub2ind(&nbsp;size(</b>Q<b>),</b>&nbsp;row<b>,</b>&nbsp;col<b>,</b>&nbsp;slice&nbsp;<b>)</b></td><td>(<i>Q</i> is a cube)</td></tr>
<tr><td>uvec&nbsp;</td><td>indices</td><td>&nbsp;=&nbsp;<b>sub2ind(&nbsp;size(</b>Q<b>),</b>&nbsp;matrix_of_subscripts&nbsp;<b>)</b></td><td></td></tr>
</tbody>
</table>
<ul>
<li>
Convert subscripts to a linear index
</li>
<br>
<li>
The argument <i><b>size(</b>X<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b>&nbsp;n_cols<b>)</b></i> or <i><b>size(</b>n_rows<b>,</b>&nbsp;n_cols<b>,</b>&nbsp;n_slices<b>)</b></i>
</li>
<br>
<li>
For the <i>matrix_of_subscripts</i> argument, the subscripts must be stored in each column of an <i>m&nbsp;x&nbsp;n</i> matrix of type <a href="#Mat">umat</a>;
<i>m=2</i> for matrix subscripts, while <i>m=3</i> for cube subscripts
</li>
<br>
<li>
A&nbsp;<i>std::logic_error</i> exception is thrown if a subscript is out of range
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat  M(4,5);
cube Q(4,5,6);

uword i = sub2ind( size(M), 2, 3 );
uword j = sub2ind( size(Q), 2, 3, 4 );
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#size">size()</a></li>
<li><a href="#ind2sub">ind2sub()</a></li>
<li><a href="#element_access">element access</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="symmat"></a>
<b>symmatu( A )</b>
<br><b>symmatu( A, do_conj )</b>
<br>
<br><b>symmatl( A )</b>
<br><b>symmatl( A, do_conj )</b>
<ul>
<li>
<i>symmatu(A)</i>: generate symmetric matrix from square matrix <i>A</i>, by reflecting the upper triangle to the lower triangle 
</li>
<br>
<li>
<i>symmatl(A)</i>: generate symmetric matrix from square matrix <i>A</i>, by reflecting the lower triangle to the upper triangle
</li>
<br>
<li>
If <i>A</i> is a complex matrix, the reflection uses the complex conjugate of the elements;
to disable the complex conjugate, set <i>do_conj</i> to <i>false</i>
</li>
<br>
<li>
If <i>A</i> is non-square, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = symmatu(A);
mat C = symmatl(A);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#trimat">trimatu() / trimatl()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Symmetric_matrix">Symmetric matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trace"></a>
<b>trace( X )</b>
<ul>
<li>
Sum of the elements on the main diagonal of matrix <i>X</i>
</li>
<br>
<li>
If <i>X</i> is an expression,
the function aims to use optimised expression evaluations to calculate only the diagonal elements
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

double x = trace(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#accu">accu()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
<li><a href="#diag">.diag()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#sum">sum()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trans"></a>
<b>trans( A )</b>
<br><b>strans( A )</b>
<ul>
<li>
For real (non-complex) matrix:
<ul>
<li><i>trans()</i> provides a transposed copy of the matrix</li>
<li><i>strans()</i> not applicable</li>
</ul>
</li>
<br>
<li>
For complex matrix:
<ul>
<li><i>trans()</i> provides a Hermitian transpose (ie. the conjugate of the elements is taken during the transpose)</li>
<li><i>strans()</i> provides a transposed copy without taking the conjugate of the elements</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 10, fill::randu);

mat B = trans(A);
mat C = A.t();    // equivalent to trans(A), but more compact
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#t_st_members">.t()</a></li>
<li><a href="#inplace_trans">inplace_trans()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trapz"></a>
<b>trapz( X, Y )</b>
<br><b>trapz( X, Y, dim )</b>
<br>
<br><b>trapz( Y )</b>
<br><b>trapz( Y, dim )</b>
<ul>
<li>
Compute the trapezoidal integral of <i>Y</i> with respect to spacing in <i>X</i>, in each column (<i>dim=0</i>) or each row (<i>dim=1</i>) of <i>Y</i>
</li>
<br>
<li>
<i>X</i> must be a vector; its length must equal either the number of rows in <i>Y</i> (when <i>dim=0</i>), or the number of columns in <i>Y</i> (when <i>dim=1</i>)
</li>
<br>
<li>
If <i>X</i> is not specified, unit spacing is used
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec X = linspace&lt;vec&gt;(0, datum::pi, 1000);
vec Y = sin(X);

mat Z = trapz(X,Y);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#sum">sum()</a></li>
<li><a href="#diff">diff()</a></li>
<li><a href="#linspace">linspace()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Numerical_integration">numerical integration in Wikipedia</a>
<li><a href="http://mathworld.wolfram.com/NumericalIntegration.html">numerical integration in MathWorld</a>
<li><a href="https://en.wikipedia.org/wiki/Trapezoidal_rule">trapezoidal rule in Wikipedia</a>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trimat"></a>
<b>trimatu( A )</b>
<br><b>trimatu( A, k )</b>
<br>
<br><b>trimatl( A )</b>
<br><b>trimatl( A, k )</b>
<ul>
<li>
Create a new matrix by copying either the upper or lower triangular part from square matrix <i>A</i>, and setting the remaining elements to zero
<ul>
<li><i>trimatu()</i> copies the upper triangular part</li>
<li><i>trimatl()</i> copies the lower triangular part</li>
</ul>
</li>
<br>
<li>
The argument <i>k</i> specifies the diagonal which inclusively delineates the boundary of the triangular part
<ul>
<li>
for <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is used (above main diagonal, towards top-right corner)
</li>
<li>
for <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is used (below main diagonal, towards bottom-left corner)
</li>
</ul>
</li>
<br>
<li>
The argument <i>k</i> is optional; by default the main diagonal is used (<i>k=0</i>)
</li>
<br>
<li>
If <i>A</i> is non-square, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat U  = trimatu(A);
mat L  = trimatl(A);

mat UU = trimatu(A,  1);  // omit the main diagonal
mat LL = trimatl(A, -1);  // omit the main diagonal
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#is_trimat">.is_trimatu() / .is_trimatl()</a></li>
<li><a href="#trimat_ind">trimatu_ind() / trimatl_ind()</a></li>
<li><a href="#symmat">symmatu() / symmatl()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#nonzeros">nonzeros()</a></li>
<li><a href="http://mathworld.wolfram.com/TriangularMatrix.html">Triangular matrix in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Triangular_matrix">Triangular matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>


<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trimat_ind"></a>
<b>trimatu_ind( size(A) )</b>
<br><b>trimatu_ind( size(A), k )</b>
<br>
<br><b>trimatl_ind( size(A) )</b>
<br><b>trimatl_ind( size(A), k )</b>
<ul>
<li>
Return a column vector containing the indices of elements that form the upper or lower triangle part of matrix <i>A</i> 
<ul>
<li><i>trimatu_ind()</i> refers to the upper triangular part</li>
<li><i>trimatl_ind()</i> refers to the lower triangular part</li>
</ul>
</li>
<br>
<li>The output vector must have the type <a href="#Col">uvec</a>
(ie. the indices are stored as unsigned integers of type <a href="#uword">uword</a>)
</li>
<br>
<li>
The argument <i>k</i> specifies the diagonal which inclusively delineates the boundary of the triangular part
<ul>
<li>
for <i>k &gt; 0</i>, the <i>k</i>-th super-diagonal is used (above main diagonal, towards top-right corner)
</li>
<li>
for <i>k &lt; 0</i>, the <i>k</i>-th sub-diagonal is used (below main diagonal, towards bottom-left corner)
</li>
</ul>
</li>
<br>
<li>
The argument <i>k</i> is optional; by default the main diagonal is used (<i>k=0</i>)
</li>
<br>
<li>
The argument <i><b>size(</b>A<b>)</b></i> can be replaced with <i><b>size(</b>n_rows<b>,</b>&nbsp;n_cols<b>)</b></i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

uvec upper_indices = trimatu_ind( size(A) );
uvec lower_indices = trimatl_ind( size(A) );

// extract upper/lower triangle into vector
vec upper_part = A(upper_indices);
vec lower_part = A(lower_indices);

// obtain indices without the main diagonal
uvec alt_upper_indices = trimatu_ind( size(A),  1);
uvec alt_lower_indices = trimatl_ind( size(A), -1);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#trimat">trimatu() / trimatl()</a></li>
<li><a href="#find">find()</a></li>
<li><a href="#submat">submatrix views</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="unique"></a>
<b>unique( A )</b>
<br>
<ul>
<li>
Return the unique elements of <i>A</i>, sorted in ascending order
</li>
<br>
<li>
If <i>A</i> is a vector, the output is also a vector with the same orientation (row or column) as <i>A</i>;
if <i>A</i> is a matrix, the output is always a column vector
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X = { { 1, 2 }
          { 2, 3 } };

mat Y = unique(X);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#find">find()</a></li>
<li><a href="#find_unique">find_unique()</a></li>
<li><a href="#sort">sort()</a></li>
<li><a href="#shuffle">shuffle()</a></li>
<li><a href="#nonzeros">nonzeros()</a></li>
<li><a href="#intersect">intersect()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="vectorise"></a>
<b>vectorise( X )</b>
<br><b>vectorise( X, dim )</b>
<br><b>vectorise( Q )</b>
<ul>
<li>
Generate a flattened version of matrix <i>X</i> or cube <i>Q</i>
</li>
<br>
<li>
The argument <i>dim</i> is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
For <i>dim=0</i>, the elements are copied from <i>X</i> column-wise, resulting in a column vector; equivalent to concatenating all the columns of <i>X</i>
</li>
<br>
<li>
For <i>dim=1</i>, the elements are copied from <i>X</i> row-wise, resulting in a row vector; equivalent to concatenating all the rows of <i>X</i>
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>column-wise vectorisation is faster than row-wise vectorisation</li>
<li>for sparse matrices, row-wise vectorisation is not recommended</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4, 5, fill::randu);

vec v = vectorise(X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#as_col_row">.as_col()&nbsp;/&nbsp;.as_row()</a></li>
<li><a href="#nonzeros">nonzeros()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="#resize">resize()</a></li>
<li><a href="#diagvec">diagvec()</a></li>
<li><a href="#as_scalar">as_scalar()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="misc_fns"></a>
<b>miscellaneous element-wise functions:</b>
<ul>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td><b>exp   </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>exp2  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>exp10 </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>trunc_exp</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>expm1</b></td></tr>
<tr><td><b>log   </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>log2  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>log10 </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>trunc_log</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>log1p</b></td></tr>
<tr><td><b>pow   </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>square</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>sqrt  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;   </b></td></tr>
<tr><td><b>floor </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>ceil  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>round </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>trunc    </b></td></tr>
<tr><td><b>erf   </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>erfc  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;   </b></td></tr>
<tr><td><b>lgamma</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;   </b></td></tr>
<tr><td><b>sign  </b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;</b></td><td>&nbsp;&nbsp;&nbsp;</td><td><b>&nbsp;   </b></td></tr>
</table>
</ul>
<ul>
<li>
Apply a function to each element
</li>
<br>
<li>
Usage:
<ul>
<li>B = fn(A)</li>
<li>A and B must have the same matrix type or cube type, such as <i>mat</i> or <i>cube</i></li>
<li>
fn(A) is one of:
<br>
<br>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
<tbody>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
       <code>exp(A)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-e exponential: <i>e<sup>&nbsp;x</sup></i>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
       <code>exp2(A)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-2 exponential: <i>2<sup>&nbsp;x</sup></i>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
       <code>exp10(A)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-10 exponential: <i>10<sup>&nbsp;x</sup></i>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>trunc_exp(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-e exponential,
      truncated to avoid infinity &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>expm1(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      compute <code>exp(A)-1</code> accurately for values of A close to zero &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
       <code>log(A)</code><sub>&nbsp;</sub>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      natural log: <i>log<sub>e</sub>&nbsp;x</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
       <code>log2(A)</code><sub>&nbsp;</sub>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-2 log: <i>log<sub><small>2</small></sub>&nbsp;x</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
       <code>log10(A)</code><sub>&nbsp;</sub>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base-10 log: <i>log<sub><small>10</small></sub>&nbsp;x</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>trunc_log(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      natural log,
      truncated to avoid &plusmn;infinity &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>log1p(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      compute <code>log(1+A)</code> accurately for values of A close to zero &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
       <code>pow(A, p)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      raise to the power of p: <i>x<sup><small>&nbsp;p</small></sup></i>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>square(A)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      square: <i>x<sup><small>&nbsp;2</small></sup></i>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
       <code>sqrt(A)</code><sup>&nbsp;</sup>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      square root: <i>x<sup>&nbsp;&frac12;</sup></i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>floor(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      largest integral value that is not greater than the input value
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>ceil(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      smallest integral value that is not less than the input value
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>round(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      round to nearest integer, with halfway cases rounded away from zero
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>trunc(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      round to nearest integer, towards zero
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>erf(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      error function &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>erfc(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      complementary error function &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr style="background-color: #F5F5F5;">
    <td style="vertical-align: top; text-align: right;">
      <code>lgamma(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      natural log of the absolute value of gamma function &nbsp; <font size=-1>(only for <i>float</i> and <i>double</i> elements)</font>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top; text-align: right;">
      <code>sign(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      signum function;
      for each element <i>a</i> in <i>A</i>, the corresponding element <i>b</i> in <i>B</i> is:
      <ul>
      <table border="0" cellpadding="0" cellspacing="0">
      <tbody>
      <tr><td>              </td><td>&#9127;&nbsp;</td><td style="text-align: right;">&minus;1</td><td>&nbsp;if <i>a</i> &lt; 0</td></tr>
      <tr><td>b&nbsp;=&nbsp;</td><td>&#9128;&nbsp;</td><td style="text-align: right;">       0</td><td>&nbsp;if <i>a</i> =    0</td></tr>
      <tr><td>              </td><td>&#9129;&nbsp;</td><td style="text-align: right;">      +1</td><td>&nbsp;if <i>a</i> &gt; 0</td></tr>
      </tbody>
      </table>
      </ul>
      if <i>a</i> is complex and non-zero, then <i>b</i> = <i>a</i> / abs(<i>a</i>)
    </td>
  </tr>
</tbody>
</table>
</li>

</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = exp(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#abs">abs()</a></li>
<li><a href="#clamp">clamp()</a></li>
<li><a href="#conj">conj()</a></li>
<li><a href="#imag_real">imag() / real()</a></li>
<li><a href="#transform">.transform()</a> &nbsp; (apply user-defined function to each element)</li>
<li><a href="#expmat">expmat()</a></li>
<li><a href="#logmat">logmat()</a></li>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#powmat">powmat()</a></li>
<li><a href="#trig_fns">trigonometric functions</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#constants">miscellaneous constants</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="trig_fns"></a>
<b>trigonometric element-wise functions (cos, sin, tan, ...)</b>
<ul>
<li>
For single argument functions, <i>B = trig_fn(A)</i>, where <i>trig_fn</i> is applied to each element in <i>A</i>, with <i>trig_fn</i> as one of:
<ul>
<li>
<i>cos</i>, <i>acos</i>, <i>cosh</i>, <i>acosh</i>
</li>
<li>
<i>sin</i>, <i>asin</i>, <i>sinh</i>, <i>asinh</i>
</li>
<li>
<i>tan</i>, <i>atan</i>, <i>tanh</i>, <i>atanh</i>
</li>
<li>
<i>sinc</i>, defined as sinc(x) = sin(&pi;x)&nbsp;/&nbsp;(&pi;x) for x&nbsp;&ne;&nbsp;0, and sinc(x) = 1 for x&nbsp;=&nbsp;0
</li>
</ul>
</li>
<br>
<li>
For dual argument functions, apply the function to each tuple of two corresponding elements in <i>X</i> and <i>Y</i>:
<ul>
<li><i>Z = atan2(Y, X)</i></li>
<li><i>Z = hypot(X, Y)</i></li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);
mat Y = cos(X);
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#misc_fns">miscellaneous element-wise functions</a></li>
<li><a href="https://en.wikipedia.org/wiki/Trigonometric_functions">trigonometric functions in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Atan2">atan2 function in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Hypot">hypot function in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Sinc_function">sinc function in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Decompositions, Factorisations, Inverses and Equation Solvers (Dense Matrices)</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="chol"></a>
<b>R = chol( X )</b>
<br><b>R = chol( X, layout )</b>
<br>
<br><b>chol( R, X )</b>
<br><b>chol( R, X, layout )</b>
<ul>
<li>
Cholesky decomposition of matrix <i>X</i>
</li>
<br>
<li>
Matrix <i>X</i> must be symmetric/hermitian and positive-definite
</li>
<br>
<li>
By default, <i>R</i> is upper triangular, such that <i>R.t()*R = X</i>
</li>
<br>
<li>
The argument <i>layout</i> is optional; <i>layout</i> is either <code>"upper"</code> or <code>"lower"</code>, which specifies whether <i>R</i> is upper or lower triangular
</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>R = chol(X)</i> resets <i>R</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>chol(R,X)</i> resets <i>R</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);
mat Y = X.t()*X;

mat R1 = chol(Y);
mat R2 = chol(Y, "lower");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#sqrtmat">sqrtmat()</a></li>
<li><a href="#lu">lu()</a></li>
<li><a href="#qr">qr()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="http://mathworld.wolfram.com/CholeskyDecomposition.html">Cholesky decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Cholesky_decomposition">Cholesky decomposition in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eig_sym"></a>
<b>vec eigval = eig_sym( X )</b>
<br>
<br><b>eig_sym( eigval,  X )</b>
<br>
<br><b>eig_sym( eigval, eigvec, X )</b>
<br><b>eig_sym( eigval, eigvec, X, method )</b>
<ul>
<li>Eigen decomposition of <b>dense</b> symmetric/hermitian matrix <i>X</i></li>
<br>
<li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
<br>
<li>The eigenvalues are in ascending order</li>
<br>
<li>The eigenvectors are stored as column vectors</li>
<br>
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
<ul>
<li>
<code>"dc"</code> indicates divide-and-conquer method (default setting)
</li>
<li>
<code>"std"</code> indicates standard method
</li>
<li>
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
</li>
</ul>
</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>eigval = eig_sym(X)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>eig_sym(eigval,X)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eig_sym(eigval,eigvec,X)</i> resets <i>eigval</i> &amp; <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<!--
<br>
<li><b>Caveat:</b> there is no explicit check whether <i>X</i> is symmetric/hermitian</li>
-->
<br>
<li>
Examples:
<ul>
<pre>
// for matrices with real elements

mat A(50, 50, fill::randu);
mat B = A.t()*A;  // generate a symmetric matrix

vec eigval;
mat eigvec;

eig_sym(eigval, eigvec, B);


// for matrices with complex elements

cx_mat C(50, 50, fill::randu);
cx_mat D = C.t()*C;

   vec eigval2;
cx_mat eigvec2;

eig_sym(eigval2, eigvec2, D);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="#eig_pair">eig_pair()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#svd_econ">svd_econ()</a></li>
<li><a href="#princomp">princomp()</a></li>
<li><a href="#eigs_sym">eigs_sym()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="#is_hermitian">.is_hermitian()</a></li>
<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues &amp; eigenvectors in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Divide-and-conquer_eigenvalue_algorithm">divide &amp; conquer eigenvalue algorithm in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eig_gen"></a>
<b>cx_vec eigval = eig_gen( X )</b>
<br><b>cx_vec eigval = eig_gen( X, bal )</b>
<br>
<br><b>eig_gen( eigval, X )</b>
<br><b>eig_gen( eigval, X, bal )</b>
<br>
<br><b>eig_gen( eigval, eigvec, X )</b>
<br><b>eig_gen( eigval, eigvec, X, bal )</b>
<br>
<br><b>eig_gen( eigval, leigvec, reigvec, X )</b>
<br><b>eig_gen( eigval, leigvec, reigvec, X, bal )</b>
<ul>
<li>Eigen decomposition of <b>dense</b> general (non-symmetric/non-hermitian) square matrix <i>X</i></li>
<br>
<li>The eigenvalues and corresponding right eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
<br>
<li>If both left and right eigenvectors are requested they are stored in <i>leigvec</i> and <i>reigvec</i>, respectively</li>
<br>
<li>The eigenvectors are stored as column vectors</li>
<br>
<li>
The <i>bal</i> argument is optional; <i>bal</i> is one of:
<ul>
<table>
<tbody>
<tr><td><code>"balance"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>diagonally scale and permute <i>X</i> to improve conditioning of the eigenvalues</td></tr>
<tr><td><code>"nobalance"</code></td><td>&nbsp;&mapsto;&nbsp;</td><td>do not balance <i>X</i>; this is the <b>default operation</b></td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>eigval = eig_gen(X)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>eig_gen(eigval,X)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eig_gen(eigval,eigvec,X)</i> resets <i>eigval</i> &amp; <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eig_gen(eigval,leigvec,reigvec,X)</i> resets <i>eigval</i>, <i>leigvec</i> &amp; <i>reigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 10, fill::randu);

cx_vec eigval;
cx_mat eigvec;

eig_gen(eigval, eigvec, A);
eig_gen(eigval, eigvec, A, "balance");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eig_pair">eig_pair()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#svd_econ">svd_econ()</a></li>
<li><a href="#schur">schur()</a></li>
<li><a href="#eigs_gen">eigs_gen()</a></li>
<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues &amp; eigenvectors in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eig_pair"></a>
<b>cx_vec eigval = eig_pair( A, B )</b>
<br>
<br><b>eig_pair( eigval, A, B )</b>
<br>
<br><b>eig_pair( eigval, eigvec, A, B )</b>
<br>
<br><b>eig_pair( eigval, leigvec, reigvec, A, B )</b>
<ul>
<li>
Eigen decomposition for pair of general <b>dense</b> square matrices <i>A</i> and <i>B</i> of the same size,
such that <i>A*eigvec&nbsp;=&nbsp;B*eigvec*diagmat(eigval)</i>
</li>
<br>
<li>The eigenvalues and corresponding right eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
<br>
<li>If both left and right eigenvectors are requested they are stored in <i>leigvec</i> and <i>reigvec</i>, respectively</li>
<br>
<li>The eigenvectors are stored as column vectors</li>
<br>
<li>If <i>A</i> or <i>B</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>eigval = eig_pair(A,B)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>eig_pair(eigval,A,B)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eig_pair(eigval,eigvec,A,B)</i> resets <i>eigval</i> &amp; <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eig_pair(eigval,leigvec,reigvec,A,B)</i> resets <i>eigval</i>, <i>leigvec</i> &amp; <i>reigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 10, fill::randu);
mat B(10, 10, fill::randu);

cx_vec eigval;
cx_mat eigvec;

eig_pair(eigval, eigvec, A, B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#qz">qz()</a></li>
<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues &amp; eigenvectors in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="hess"></a>
<b>H = hess( X )</b>
<br>
<br><b>hess( H,  X )</b>
<br>
<br><b>hess( U, H, X )</b>
<ul>
<li>Upper Hessenberg decomposition of square matrix <i>X</i>, such that <i>X = U*H*U.t()</i></li>
<br>
<li><i>U</i> is a unitary matrix containing the Hessenberg vectors</li>
<br>
<li><i>H</i> is a square matrix known as the upper Hessenberg matrix, with elements below the first subdiagonal set to zero</li>
<br>
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>H = hess(X)</i> resets <i>H</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>hess(H,X)</i> resets <i>H</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>hess(U,H,X)</i> resets <i>U</i> &amp; <i>H</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> in general, upper Hessenberg decomposition is not unique
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(20,20, fill::randu);

mat U;
mat H;

hess(U, H, X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#qz">qz()</a></li>
<li><a href="#schur">schur()</a></li>
<li><a href="http://mathworld.wolfram.com/HessenbergDecomposition.html">Hessenberg decomposition in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Hessenberg_matrix">Hessenberg matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="inv"></a>
<b>B = inv( A )</b>
<br><b>inv( B, A )</b>
<ul>
<li>
Inverse of general square matrix <i>A</i>
</li>
<br>
<li>
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>If <i>A</i> appears to be singular:
<ul>
<li><i>B = inv(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>inv(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>if matrix <i>A</i> is know to be symmetric positive definite, using <a href="#inv_sympd">inv_sympd()</a> is faster</li>
<li>if matrix <i>A</i> is know to be diagonal, use <i>inv(&nbsp;diagmat(A)&nbsp;)</i></li>
<li>if matrix <i>A</i> is know to be triangular, use <i>inv(&nbsp;trimatu(A)&nbsp;)</i> or <i>inv(&nbsp;trimatl(A)&nbsp;)</i></li>
<li>to solve a system of linear equations, such as <i>Z&nbsp;=&nbsp;inv(X)*Y</i>, using <a href="#solve">solve()</a> can be faster and/or more accurate</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B = inv(A);
</pre>
</ul>
</li>
<br>
<li>
See also: 
<ul>
<li><a href="#i_member">.i()</a>
<li><a href="#inv_sympd">inv_sympd()</a>
<li><a href="#rcond">rcond()</a>
<li><a href="#pinv">pinv()</a>
<li><a href="#solve">solve()</a></li>
<li><a href="#spsolve">spsolve()</a></li>
<li><a href="#diagmat">diagmat()</a></li>
<li><a href="#trimat">trimatu() / trimatl()</a></li>
<li><a href="#powmat">powmat()</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="inv_sympd"></a>
<b>B = inv_sympd( A )</b>
<br><b>inv_sympd( B, A )</b>
<ul>
<li>
Inverse of symmetric/hermitian positive definite matrix <i>A</i>
</li>
<br>
<li>
If <i>A</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>If <i>A</i> appears to be singular or not positive definite:
<ul>
<li><i>B = inv_sympd(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>inv_sympd(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<!--
<br>
<li><b>Caveat:</b> there is no explicit check whether <i>A</i> is symmetric/hermitian positive definite</li>
-->
<br>
<li>
<b>Caveat:</b> 
to solve a system of linear equations, such as <i>Z&nbsp;=&nbsp;inv(X)*Y</i>,
using <a href="#solve">solve()</a> can be faster and/or more accurate
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B = A.t() * A;
mat C = inv_sympd(B);
</pre>
</ul>
</li>
<br>
<li>
See also: 
<ul>
<li><a href="#inv">inv()</a>
<li><a href="#rcond">rcond()</a>
<li><a href="#pinv">pinv()</a>
<li><a href="#solve">solve()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="http://mathworld.wolfram.com/MatrixInverse.html">matrix inverse in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Invertible_matrix">invertible matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Positive-definite_matrix">positive definite matrix in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="lu"></a>
<b>lu( L, U, P, X )</b>
<br><b>lu( L, U, X )</b>
<ul>
<li>
Lower-upper decomposition (with partial pivoting) of matrix <i>X</i>
</li>
<br>
<li>
The first form provides 
a lower-triangular matrix <i>L</i>,
an upper-triangular matrix <i>U</i>,
and a permutation matrix <i>P</i>,
such that <i>P.t()*L*U&nbsp;=&nbsp;X</i>
</li>
<br>
<li>
The second form provides permuted <i>L</i> and <i>U</i>, such that <i>L*U = X</i>;
note that in this case <i>L</i> is generally not lower-triangular
</li>
<br>
<li>
If the decomposition fails:
<ul>
<li><i>lu(L,U,P,X)</i> resets <i>L</i>, <i>U</i>, <i>P</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>lu(L,U,X)</i> resets <i>L</i>, <i>U</i>  and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat L, U, P;

lu(L, U, P, A);

mat B = P.t()*L*U;
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#chol">chol()</a></li>
<li><a href="http://en.wikipedia.org/wiki/LU_decomposition">LU decomposition in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/LUDecomposition.html">LU decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="null"></a>
<b>B = null( A )</b>
<br><b>B = null( A, tolerance )</b>
<br>
<br><b>null( B, A )</b>
<br><b>null( B, A, tolerance )</b>
<ul>
<li>
Find the orthonormal basis of the null space of matrix <i>A</i>
</li>
<br>
<li>
The dimension of the range space is the number of singular values of <i>A</i> not greater than <i>tolerance</i>
</li>
<br>
<li>
The <i>tolerance</i> argument is optional; by default <i>tolerance</i> is <i>max(m,n)*max_sv*datum::eps</i>, where:
<ul>
<li><i>m</i> = number of rows and <i>n</i> = number of columns in <i>A</i></li>
<li><i>max_sv</i> = maximal singular value of <i>A</i></li>
<li><i>datum::eps</i> = difference between 1 and the least value greater than 1 that is representable</li>
</ul>
</li>
<br>
<li>
The computation is based on singular value decomposition; if the decomposition fails:
<ul>
<li><i>B = null(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>null(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);

A.row(0).zeros();
A.col(0).zeros();

mat B = null(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#orth">orth()</a></li>
<li><a href="#qr">qr()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#rank">rank()</a></li>
<li><a href="#constants">datum::eps</a></li>
<li><a href="http://en.wikipedia.org/wiki/Orthonormal_basis">Orthonormal basis in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="orth"></a>
<b>B = orth( A )</b>
<br><b>B = orth( A, tolerance )</b>
<br>
<br><b>orth( B, A )</b>
<br><b>orth( B, A, tolerance )</b>
<ul>
<li>
Find the orthonormal basis of the range space of matrix <i>A</i>,
so that <i>B.t()*B&nbsp;&asymp;&nbsp;eye(r,r)</i>, where <i>r&nbsp;=&nbsp;rank(A)</i>
</li>
<br>
<li>
The dimension of the range space is the number of singular values of <i>A</i> greater than <i>tolerance</i>
</li>
<br>
<li>
The <i>tolerance</i> argument is optional; by default <i>tolerance</i> is <i>max(m,n)*max_sv*datum::eps</i>, where:
<ul>
<li><i>m</i> = number of rows and <i>n</i> = number of columns in <i>A</i></li>
<li><i>max_sv</i> = maximal singular value of <i>A</i></li>
<li><i>datum::eps</i> = difference between 1 and the least value greater than 1 that is representable</li>
</ul>
</li>
<br>
<li>
The computation is based on singular value decomposition; if the decomposition fails:
<ul>
<li><i>B = orth(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>orth(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 6, fill::randu);

mat B = orth(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#null">null()</a></li>
<li><a href="#qr">qr()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#rank">rank()</a></li>
<li><a href="#constants">datum::eps</a></li>
<li><a href="http://en.wikipedia.org/wiki/Orthonormal_basis">Orthonormal basis in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="pinv"></a>
<b>B = pinv( A )</b>
<br><b>B = pinv( A, tolerance )</b>
<br><b>B = pinv( A, tolerance, method )</b>
<br>
<br><b>pinv( B, A )</b>
<br><b>pinv( B, A, tolerance )</b>
<br><b>pinv( B, A, tolerance, method )</b>
<ul>
<li>Moore-Penrose pseudo-inverse of matrix <i>A</i></li>
<br>
<li>
The computation is based on singular value decomposition
</li>
<br>
<li>The <i>tolerance</i> argument is optional</li>
<br>
<li>The default tolerance is <i>max(m,n)*max_sv*datum::eps</i>, where:
<ul>
<li><i>m</i> = number of rows and <i>n</i> = number of columns in <i>A</i></li>
<li><i>max_sv</i> = maximal singular value of <i>A</i></li>
<li><i>datum::eps</i> = difference between 1 and the least value greater than 1 that is representable</li>
</ul>
</li>
<br>
<li>Any singular values less than <i>tolerance</i> are treated as zero</li>
<br>
<li>
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
<ul>
<li>
<code>"dc"</code> indicates divide-and-conquer method (default setting)
</li>
<li>
<code>"std"</code> indicates standard method
</li>
<li>
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
</li>
</ul>
</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>B = pinv(A)</i> resets <i>B</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>pinv(B,A)</i> resets <i>B</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(4, 5, fill::randu);

mat B = pinv(A);        // use default tolerance

mat C = pinv(A, 0.01);  // set tolerance to 0.01
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#i_member">.i()</a></li>
<li><a href="#inv">inv()</a></li>
<li><a href="#solve">solve()</a></li>
<li><a href="#spsolve">spsolve()</a></li>
<li><a href="#constants">datum::eps</a></li>
<li><a href="http://mathworld.wolfram.com/Pseudoinverse.html">Pseudoinverse in MathWorld</a></li>
<li><a href="http://mathworld.wolfram.com/Moore-PenroseMatrixInverse.html">Moore-Penrose Matrix Inverse in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse">Moore-Penrose pseudoinverse in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="qr"></a>
<table>
<tr><td><b>qr( Q, R,    X           )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 1)</td></tr>
<tr><td><b>qr( Q, R, P, X, "vector" )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 2)</td></tr>
<tr><td><b>qr( Q, R, P, X, "matrix" )</b></td><td>&nbsp;&nbsp;&nbsp;</td><td>(form 3)</td></tr>
</table>
<ul>
<li>
Decomposition of <i>X</i> into an orthogonal matrix <i>Q</i> and a right triangular matrix <i>R</i>,
with an optional permutation matrix/vector <i>P</i>
<ul>
<li>form 1: decomposition has the form <i>Q*R = X</i></li>
<li>form 2: <i>P</i> is permutation vector with type <a href="#Col">uvec</a>; decomposition has the form <i>Q*R = X.cols(P)</i></li>
<li>form 3: <i>P</i> is permutation matrix with type <a href="#Mat">umat</a>; decomposition has the form <i>Q*R = X*P</i></li>
</ul>
</li>
<br>
<li>
If <i>P</i> is specified, a column pivoting decomposition is used;
the diagonal entries of <i>R</i> are ordered from largest to smallest magnitude
</li>
<br>
<li>
If the decomposition fails, <i>Q</i>, <i>R</i> and <i>P</i> are reset and the function returns a bool set to <i>false</i> (exception is not thrown)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);

mat Q;
mat R;

qr(Q, R, X);

uvec P_vec;
umat P_mat;

qr(Q, R, P_vec, X, "vector");
qr(Q, R, P_mat, X, "matrix");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#qr_econ">qr_econ()</a></li>
<li><a href="#chol">chol()</a></li>
<li><a href="#orth">orth()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Orthogonal_matrix">orthogonal matrix in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="qr_econ"></a>
<b>qr_econ( Q, R, X )</b>
<ul>
<li>
Economical decomposition of <i>X</i> (with size <i>m</i> x <i>n</i>) into an orthogonal matrix <i>Q</i> and a right triangular matrix <i>R</i>, such that <i>Q*R = X</i>
</li>
<br>
<li>
If <i>m</i> &gt; <i>n</i>, only the first <i>n</i> rows of <i>R</i> and the first <i>n</i> columns of <i>Q</i> are calculated 
(ie. the zero rows of <i>R</i> and the corresponding columns of <i>Q</i> are omitted)
</li>
<br>
<li>
If the decomposition fails, <i>Q</i> and <i>R</i> are reset and the function returns a bool set to <i>false</i> (exception is not thrown)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(6, 5, fill::randu);

mat Q;
mat R;

qr_econ(Q, R, X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#qr">qr()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Orthogonal_matrix">orthogonal matrix in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/QR_decomposition">QR decomposition in Wikipedia</a></li>
<li><a href="http://octave.sourceforge.net/octave/function/qr.html">QR decomposition in Octave</a></li>
<li><a href="http://mathworld.wolfram.com/QRDecomposition.html">QR decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="qz"></a>
<b>qz( AA, BB, Q, Z, A, B )</b>
<br><b>qz( AA, BB, Q, Z, A, B, select )</b>
<ul>
<li>
Generalised Schur decomposition for pair of general square matrices <i>A</i> and <i>B</i> of the same size,
<br>such that <i>A&nbsp;=&nbsp;Q.t()*AA*Z.t()</i> and <i>B&nbsp;=&nbsp;Q.t()*BB*Z.t()</i>
</li>
<br>
<li>The <i>select</i> argument is optional and specifies the ordering of the top left of the Schur form; it is one of the following:
<br>
<ul>
<table>
<tbody>
<tr><td><code>"none"</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>no ordering (default operation)</td></tr>
<tr><td><code>"lhp"</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>left-half-plane: eigenvalues with real part &lt; 0</td></tr>
<tr><td><code>"rhp"</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>right-half-plane: eigenvalues with real part &gt; 0</td></tr>
<tr><td><code>"iuc"</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>inside-unit-circle: eigenvalues with absolute value &lt; 1</td></tr>
<tr><td><code>"ouc"</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>outside-unit-circle: eigenvalues with absolute value &gt; 1</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>The left and right Schur vectors are stored in <i>Q</i> and <i>Z</i>, respectively</li>
<br>
<li>In the complex-valued problem, the generalised eigenvalues are found in <i>diagvec(AA) / diagvec(BB)</i></li>
<br>
<li>If <i>A</i> or <i>B</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails, <i>AA</i>, <i>BB</i>, <i>Q</i> and <i>Z</i> are reset, and the function returns a bool set to <i>false</i> (exception is not thrown)</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(10, 10, fill::randu);
mat B(10, 10, fill::randu);

mat AA;
mat BB;
mat Q;
mat Z; 

qz(AA, BB, Q, Z, A, B);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#hess">hess()</a></li>
<li><a href="#schur">schur()</a></li>
<li><a href="#eig_pair">eig_pair()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Schur_decomposition#Generalized_Schur_decomposition">generalised Schur decomposition in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="schur"></a>
<b>S = schur( X )</b>
<br>
<br><b>schur( S,  X )</b>
<br>
<br><b>schur( U, S, X )</b>
<ul>
<li>Schur decomposition of square matrix <i>X</i>, such that <i>X = U*S*U.t()</i></li>
<br>
<li><i>U</i> is a unitary matrix containing the Schur vectors</li>
<br>
<li><i>S</i> is an upper triangular matrix, called the Schur form of <i>X</i></li>
<br>
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>S = schur(X)</i> resets <i>S</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>schur(S,X)</i> resets <i>S</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>schur(U,S,X)</i> resets <i>U</i> &amp; <i>S</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
<b>Caveat:</b> in general, Schur decomposition is not unique
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(20,20, fill::randu);

mat U;
mat S;

schur(U, S, X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#hess">hess()</a></li>
<li><a href="#qz">qz()</a></li>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="http://mathworld.wolfram.com/SchurDecomposition.html">Schur decomposition in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Schur_decomposition">Schur decomposition in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="solve"></a>
<b>X = solve( A, B )</b>
<br><b>X = solve( A, B, settings )</b>
<br>
<br><b>solve( X, A, B )</b>
<br><b>solve( X, A, B, settings )</b>
<ul>
<li>Solve a <b>dense</b> system of linear equations, <i>A*X = B</i>, where <i>X</i> is unknown;
similar functionality to the \ operator in Matlab/Octave, ie. <i>X&nbsp;=&nbsp;A&nbsp;\&nbsp;B</i>
</li>
<br>
<li><i>A</i> can be square sized (critically determined system), or non-square (under/over-determined system)
</li>
<br>
<li>
<i>B</i> can be a vector or matrix
</li>
<br>
<li>
The number of rows in <i>A</i> and <i>B</i> must be the same
</li>
<br>
<li>
By default, matrix <i>A</i> is analysed to automatically determine whether it is a general matrix, band matrix, diagonal matrix, or symmetric/hermitian positive definite (SPD) matrix;
based on the detected matrix structure, a specialised solver is used for faster execution;
see the <a href="armadillo_solver_2020.pdf">associated paper</a> for more details
</li>
<br>
<li>
If <i>A</i> is known to be a triangular matrix,
the solution can be computed faster by explicitly indicating that <i>A</i> is triangular through <a href="#trimat">trimatu()</a> or <a href="#trimat">trimatl()</a>; see examples below
</li>
<br>
<li>The <i>settings</i> argument is optional; it is one of the following, or a combination thereof:
<br>
<br>
<table>
<tbody>
<tr><td><code>solve_opts::fast</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>fast mode: disable determining solution quality via rcond, disable iterative refinement, disable equilibration</td></tr>
<tr><td><code>solve_opts::refine</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>apply iterative refinement to improve solution quality &nbsp; (matrix <i>A</i> must be square)</td></tr>
<tr><td><code>solve_opts::equilibrate</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>equilibrate the system before solving &nbsp; (matrix <i>A</i> must be square)</td></tr>
<tr><td><code>solve_opts::likely_sympd</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>indicate that matrix <i>A</i> is likely symmetric/hermitian positive definite</td></tr>
<tr><td><code>solve_opts::allow_ugly</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>keep solutions of systems that are singular to working precision</td></tr>
<tr><td><code>solve_opts::no_approx</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>do not find approximate solutions for rank deficient systems</td></tr>
<tr><td><code>solve_opts::no_band</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>do not use specialised solver for band matrices or diagonal matrices</td></tr>
<tr><td><code>solve_opts::no_trimat</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>do not use specialised solver for triangular matrices</td></tr>
<tr><td><code>solve_opts::no_sympd</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>do not use specialised solver for symmetric/hermitian positive definite matrices</td></tr>
</tbody>
</table>
<br>
the above settings can be combined using the <code>+</code> operator; for example: <code>solve_opts::fast&nbsp;+&nbsp;solve_opts::no_approx</code>
</li>
<br>
<li>
<b>Caveat:</b> using <i><code>solve_opts::fast</code></i> will speed up finding the solution, but for poorly conditioned systems the solution may have lower quality 
</li>
<br>
<li>
<b>Caveat:</b> not all SPD matrices are automatically detected; to skip the analysis step and directly indicate that matrix <i>A</i> is likely SPD, use <code>solve_opts::likely_sympd</code>
</li>
<br>
<li>
If no solution is found:
<ul>
<li><i>X = solve(A,B)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>solve(X,A,B)</i> resets <i>X</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
vec b(5,    fill::randu);
mat B(5, 5, fill::randu);

vec x1 = solve(A, b);

vec x2;
bool status = solve(x2, A, b);

mat X1 = solve(A, B);

mat X2 = solve(A, B, solve_opts::fast);  // enable fast mode

mat X3 = solve(trimatu(A), B);  // indicate that A is triangular
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#inv">inv()</a></li>
<li><a href="#pinv">pinv()</a></li>
<li><a href="#rcond">rcond()</a></li>
<li><a href="#roots">roots()</a></li>
<li><a href="#syl">syl()</a></li>
<li><a href="#spsolve">spsolve()</a></li>
<li><a href="http://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Band_matrix">band matrix in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Definiteness_of_a_matrix">definiteness of a matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/PositiveDefiniteMatrix.html">positive definite matrix in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Iterative_refinement">iterative refinement</a></li>
<li><a href="armadillo_solver_2020.pdf">An Adaptive Solver for Systems of Linear Equations</a> - paper detailing the internal implementation of solve()</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="svd"></a>
<b>vec s = svd( X )</b>
<br>
<br><b>svd( vec s, X )</b>
<br>
<br><b>svd( mat U, vec s, mat V, mat X )</b>
<br><b>svd( mat U, vec s, mat V, mat X, method )</b>
<br>
<br><b>svd( cx_mat U, vec s, cx_mat V, cx_mat X )</b>
<br><b>svd( cx_mat U, vec s, cx_mat V, cx_mat X, method )</b>
<ul>
<li>
Singular value decomposition of <b>dense</b> matrix <i>X</i>
</li>
<br>
<li>If <i>X</i> is square, it can be reconstructed using <i>X = U*diagmat(s)*V.t()</i>
</li>
<br>
<li>
The singular values are in descending order
</li>
<br>
<li>
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
<ul>
<li>
<code>"dc"</code> indicates divide-and-conquer method (default setting)
</li>
<li>
<code>"std"</code> indicates standard method
</li>
<li>
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
</li>
</ul>
</li>
<br>
<li>
If the decomposition fails, the output objects are reset and:
<ul>
<li><i>s = svd(X)</i> resets <i>s</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>svd(s,X)</i> resets <i>s</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>svd(U,s,V,X)</i> resets <i>U</i>, <i>s</i>, <i>V</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);

mat U;
vec s;
mat V;

svd(U,s,V,X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#svd_econ">svd_econ()</a></li>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#princomp">princomp()</a></li>
<li><a href="#svds">svds()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="svd_econ"></a>
<b>svd_econ( mat U, vec s, mat V, mat X )</b>
<br><b>svd_econ( mat U, vec s, mat V, mat X, mode )</b>
<br><b>svd_econ( mat U, vec s, mat V, mat X, mode, method )</b>
<br>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X )</b>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, mode )</b>
<br><b>svd_econ( cx_mat U, vec s, cx_mat V, cx_mat X, mode, method )</b>
<ul>
<li>
Economical singular value decomposition of <b>dense</b> matrix <i>X</i>
</li>
<br>
<li>
The singular values are in descending order
</li>
<br>
<li>
The <i>mode</i> argument is optional; <i>mode</i> is one of:
<ul>
<table>
<tbody>
<tr><td></td><td style="text-align: left;"><code>"both"</code></td><td>&nbsp;=&nbsp;</td><td>compute both left and right singular vectors (default operation)</td></tr>
<tr><td></td><td style="text-align: left;"><code>"left"</code></td><td>&nbsp;=&nbsp;</td><td>compute only left singular vectors</td></tr>
<tr><td></td><td style="text-align: left;"><code>"right"</code></td><td>&nbsp;=&nbsp;</td><td>compute only right singular vectors</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>method</i> argument is optional; <i>method</i> is either <code>"dc"</code> or <code>"std"</code>
<ul>
<li>
<code>"dc"</code> indicates divide-and-conquer method (default setting)
</li>
<li>
<code>"std"</code> indicates standard method
</li>
<li>
the divide-and-conquer method provides slightly different results than the standard method, but is considerably faster for large matrices
</li>
</ul>
</li>
<br>
<li>
If the decomposition fails, <i>U</i>, <i>s</i>, <i>V</i> are reset and a bool set to <i>false</i> is returned (exception is not thrown)
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4, 5, fill::randu);

mat U;
vec s;
mat V;

svd_econ(U, s, V, X);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#svd">svd()</a></li>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#princomp">princomp()</a></li>
<li><a href="#svds">svds()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="syl"></a>
<b>X = syl( A, B, C )</b>
<br><b>syl( X, A, B, C )</b>
<ul>
<li>Solve the Sylvester equation, ie. <i>AX + XB + C = 0</i>, where <i>X</i> is unknown</li>
<br>
<li>Matrices <i>A</i>, <i>B</i> and <i>C</i> must be square sized</li>
<br>
<li>
If no solution is found:
<ul>
<li><i>syl(A,B,C)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>syl(X,A,B,C)</i> resets <i>X</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);
mat B(5, 5, fill::randu);
mat C(5, 5, fill::randu);

mat X1 = syl(A, B, C);

mat X2;
syl(X2, A, B, C);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#solve">solve()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Sylvester_equation">Sylvester equation in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Decompositions, Factorisations and Equation Solvers (Sparse Matrices)</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eigs_sym"></a>
<b>vec eigval = eigs_sym( X, k )</b>
<br><b>vec eigval = eigs_sym( X, k, form )</b>
<br><b>vec eigval = eigs_sym( X, k, form, opts )</b>
<br>
<br><b>eigs_sym( eigval, X, k )</b>
<br><b>eigs_sym( eigval, X, k, form )</b>
<br><b>eigs_sym( eigval, X, k, form, opts )</b>
<br>
<br><b>eigs_sym( eigval, eigvec, X, k )</b>
<br><b>eigs_sym( eigval, eigvec, X, k, form )</b>
<br><b>eigs_sym( eigval, eigvec, X, k, form, opts )</b>
<ul>
<li>Obtain a limited number of eigenvalues and eigenvectors of <b>sparse</b> symmetric real matrix <i>X</i></li>
<br>
<li>
<i>k</i> specifies the number of eigenvalues and eigenvectors
</li>
<br>
<li>The argument <i>form</i> is optional; <i>form</i> is one of:
<ul>
<table>
<tbody>
<tr><td><code>"lm"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with largest magnitude (default operation)</td></tr>
<tr><td><code>"sm"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with smallest magnitude (see caveat below)</td></tr>
<tr><td><code>"la"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with largest algebraic value</td></tr>
<tr><td><code>"sa"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with smallest algebraic value</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>opts</i> argument is optional; <i>opts</i> is an instance of the <i>eigs_opts</i> structure:
<ul>
<pre>
struct eigs_opts
  {
  double       tol;     // default: 0
  unsigned int maxiter; // default: 1000
  unsigned int subdim;  // default: max(2*k+1, 20)
  };
</pre>
</ul>
<ul>
<li><i>tol</i> specifies the tolerance for convergence</li>
<li><i>maxiter</i> specifies the maximum number of Arnoldi iterations</li>
<li><i>subdim</i> specifies the dimension of the Krylov subspace, with the constraint <code>k &lt; subdim &le; X.n_rows</code>; recommended value is <code>subdim &ge; 2*k</code></li>
</ul>
</li>
<br>
<li>The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively</li>
<br>
<li>If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>eigval = eigs_sym(X,k)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>eigs_sym(eigval,X,k)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eigs_sym(eigval,eigvec,X,k)</i> resets <i>eigval</i> &amp; <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li><b>Caveats:</b>
<ul>
<li>the number of obtained eigenvalues/eigenvectors may be lower than requested, depending on the given data</li>
<li>
if the decomposition fails, try first increasing <i>opts.subdim</i> (Krylov subspace dimension),
and, as secondary options, try increasing <i>opts.maxiter</i> (maximum number of iterations),
and/or <i>opts.tol</i> (tolerance for convergence), and/or <i>k</i> (number of eigenvalues)
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
// generate sparse matrix
sp_mat A = sprandu&lt;sp_mat&gt;(1000, 1000, 0.1);
sp_mat B = A.t()*A;

vec eigval;
mat eigvec;

eigs_sym(eigval, eigvec, B, 5);  // find 5 eigenvalues/eigenvectors

eigs_opts opts;
opts.maxiter = 10000;            // increase max iterations to 10000

eigs_sym(eigval, eigvec, B, 5, "lm", opts);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eigs_gen">eigs_gen()</a></li>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#svds">svds()</a></li>
<li><a href="#is_symmetric">.is_symmetric()</a></li>
<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues &amp; eigenvectors in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="eigs_gen"></a>
<b>cx_vec eigval = eigs_gen( X, k )</b>
<br><b>cx_vec eigval = eigs_gen( X, k, form )</b>
<br><b>cx_vec eigval = eigs_gen( X, k, form, opts )</b>
<br>
<br><b>eigs_gen( eigval, X, k )</b>
<br><b>eigs_gen( eigval, X, k, form )</b>
<br><b>eigs_gen( eigval, X, k, form, opts )</b>
<br>
<br><b>eigs_gen( eigval, eigvec, X, k )</b>
<br><b>eigs_gen( eigval, eigvec, X, k, form )</b>
<br><b>eigs_gen( eigval, eigvec, X, k, form, opts )</b>
<ul>
<li>
Obtain a limited number of eigenvalues and eigenvectors of <b>sparse</b> general (non-symmetric/non-hermitian) square matrix <i>X</i>
</li>
<br>
<li>
<i>k</i> specifies the number of eigenvalues and eigenvectors
</li>
<br>
<li>The argument <i>form</i> is optional; <i>form</i> is one of:
<ul>
<table>
<tbody>
<tr><td><code>"lm"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with largest magnitude (default operation)</td></tr>
<tr><td><code>"sm"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with smallest magnitude (see caveat below)</td></tr>
<tr><td><code>"lr"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with largest real part</td></tr>
<tr><td><code>"sr"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with smallest real part</td></tr>
<tr><td><code>"li"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with largest imaginary part</td></tr>
<tr><td><code>"si"</code></td><td>&nbsp;=&nbsp;</td><td>obtain eigenvalues with smallest imaginary part</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>opts</i> argument is optional; <i>opts</i> is an instance of the <i>eigs_opts</i> structure:
<ul>
<pre>
struct eigs_opts
  {
  double       tol;     // default: 0
  unsigned int maxiter; // default: 1000
  unsigned int subdim;  // default: max(2*k+1, 20)
  };
</pre>
</ul>
<ul>
<li><i>tol</i> specifies the tolerance for convergence</li>
<li><i>maxiter</i> specifies the maximum number of Arnoldi iterations</li>
<li><i>subdim</i> specifies the dimension of the Krylov subspace, with the constraint <code>k + 2 &lt; subdim &le; X.n_rows</code>; recommended value is <code>subdim &ge; 2*k + 1</code></li>
</ul>
</li>
<br>
<li>
The eigenvalues and corresponding eigenvectors are stored in <i>eigval</i> and <i>eigvec</i>, respectively
</li>
<br>
<li>
If <i>X</i> is not square sized, a <i>std::logic_error</i> exception is thrown
</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>eigval = eigs_gen(X,k)</i> resets <i>eigval</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>eigs_gen(eigval,X,k)</i> resets <i>eigval</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>eigs_gen(eigval,eigvec,X,k)</i> resets <i>eigval</i> &amp; <i>eigvec</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li><b>Caveats:</b>
<ul>
<li>the number of obtained eigenvalues/eigenvectors may be lower than requested, depending on the given data</li>
<li>
if the decomposition fails, try first increasing <i>opts.subdim</i> (Krylov subspace dimension),
and, as secondary options, try increasing <i>opts.maxiter</i> (maximum number of iterations),
and/or <i>opts.tol</i> (tolerance for convergence), and/or <i>k</i> (number of eigenvalues)
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
// generate sparse matrix
sp_mat A = sprandu&lt;sp_mat&gt;(1000, 1000, 0.1);  

cx_vec eigval;
cx_mat eigvec;

eigs_gen(eigval, eigvec, A, 5);  // find 5 eigenvalues/eigenvectors

eigs_opts opts;
opts.maxiter = 10000;            // increase max iterations to 10000

eigs_gen(eigval, eigvec, A, 5, "lm", opts);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eigs_sym">eigs_sym()</a></li>
<li><a href="#eig_gen">eig_gen()</a></li>
<li><a href="#svds">svds()</a></li>
<li><a href="http://mathworld.wolfram.com/EigenDecomposition.html">eigen decomposition in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors">eigenvalues &amp; eigenvectors in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="spsolve"></a>
<b>X = spsolve( A, B )</b>
<br><b>X = spsolve( A, B, solver )</b>
<br><b>X = spsolve( A, B, solver, opts )</b>
<br>
<br><b>spsolve( X, A, B )</b>
<br><b>spsolve( X, A, B, solver )</b>
<br><b>spsolve( X, A, B, solver, opts )</b>
<br>
<ul>
<li>
Solve a <b>sparse</b> system of linear equations, <i>A*X = B</i>, where <i>A</i> is a sparse matrix, <i>B</i> is a dense matrix or vector, and <i>X</i> is unknown
</li>
<br>
<li>
The number of rows in <i>A</i> and <i>B</i> must be the same
</li>
<br>
<li>
If no solution is found:
<ul>
<li><i>X = spsolve(A, B)</i> resets <i>X</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>spsolve(X, A, B)</i> resets <i>X</i> and returns a bool set to <i>false</i> (no exception is thrown)</li>
</ul>
</li>
<br>
<li>
The <i>solver</i> argument is optional; <i>solver</i> is either <code>"superlu"</code> or <code>"lapack"</code>; by default <code>"superlu"</code> is used
<ul>
<li>
For <code>"superlu"</code>, <i>ARMA_USE_SUPERLU</i> must be enabled in <a href="#config_hpp">config.hpp</a>
</li>
<li>
For <code>"lapack"</code>, sparse matrix <i>A</i> is converted to a dense matrix before using the LAPACK solver; this considerably increases memory usage
</li>
</ul>
</li>
<br>
<li>
<b>Notes</b>:
<ul>
<li>The SuperLU solver is mainly useful for very large and/or very sparse matrices</li>
<li>If you have sufficient amount of memory to store a dense version of matrix <i>A</i>, the LAPACK solver can be faster</li>
</ul>
</li>
<br>
<li>
The <i>opts</i> argument is optional and applicable to the SuperLU solver;
<br><i>opts</i> is an instance of the <i>superlu_opts</i> structure:
<ul>
<pre>
struct superlu_opts
  {
  bool             allow_ugly;   // default: false
  bool             equilibrate;  // default: false
  bool             symmetric;    // default: false
  double           pivot_thresh; // default: 1.0
  permutation_type permutation;  // default: superlu_opts::COLAMD
  refine_type      refine;       // default: superlu_opts::REF_NONE
  };
</pre>
</ul>
<ul>
<li>
<i>allow_ugly</i> is either <i>true</i> or <i>false</i>; indicates whether to keep solutions of systems singular to working precision
</li>
<br>
<li>
<i>equilibrate</i> is either <i>true</i> or <i>false</i>; indicates whether to equilibrate the system (scale the rows and columns of <i>A</i> to have unit norm)
</li>
<br>
<li>
<i>symmetric</i> is either <i>true</i> or <i>false</i>; indicates whether to use SuperLU symmetric mode, which gives preference to diagonal pivots
</li>
<br>
<li>
<i>pivot_threshold</i> is in the range [0.0,&nbsp;1.0], used for determining whether a diagonal entry is an acceptable pivot (details in SuperLU documentation)
</li>
<br>
<li>
<i>permutation</i> specifies the type of column permutation; it is one of:
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tr><td><code>superlu_opts::NATURAL</code></td><td>&nbsp;&nbsp;</td><td>natural ordering</td></tr>
<tr><td><code>superlu_opts::MMD_ATA</code></td><td>&nbsp;&nbsp;</td><td>minimum degree ordering on structure of <code>A.t()&nbsp;*&nbsp;A</code></td></tr>
<tr><td><code>superlu_opts::MMD_AT_PLUS_A</code></td><td>&nbsp;&nbsp;</td><td>minimum degree ordering on structure of <code>A.t()&nbsp;+&nbsp;A</code></td></tr>
<tr><td><code>superlu_opts::COLAMD</code></td><td>&nbsp;&nbsp;</td><td>approximate minimum degree column ordering</td></tr>
</table>
</ul>
</li>
<br>
<li>  
<i>refine</i> specifies the type of iterative refinement; it is one of:
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tr><td><code>superlu_opts::REF_NONE</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>no refinement</td></tr>
<tr><td><code>superlu_opts::REF_SINGLE</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>iterative refinement in single precision</td></tr>
<tr><td><code>superlu_opts::REF_DOUBLE</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>iterative refinement in double precision</td></tr>
<tr><td><code>superlu_opts::REF_EXTRA</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>iterative refinement in extra precision</td></tr>
</table>
</ul>
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat A = sprandu&lt;sp_mat&gt;(1000, 1000, 0.1);

vec b(1000,    fill::randu);
mat B(1000, 5, fill::randu);

vec x = spsolve(A, b);  // solve one system
mat X = spsolve(A, B);  // solve several systems

bool status = spsolve(x, A, b);  // use default solver
if(status == false)  { cout &lt;&lt; "no solution" &lt;&lt; endl; }

spsolve(x, A, b, "lapack" );  // use LAPACK  solver
spsolve(x, A, b, "superlu");  // use SuperLU solver

superlu_opts opts;

opts.allow_ugly  = true;
opts.equilibrate = true;

spsolve(x, A, b, "superlu", opts);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#solve">solve()</a></li>
<li><a href="http://crd-legacy.lbl.gov/~xiaoye/SuperLU/">SuperLU home page</a>
<li><a href="http://mathworld.wolfram.com/LinearSystemofEquations.html">linear system of equations in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Linear_system_of_equations">system of linear equations in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="svds"></a>
<b>vec s = svds( X, k )</b>
<br><b>vec s = svds( X, k, tol )</b>
<br>
<br><b>svds( vec s, X, k )</b> 
<br><b>svds( vec s, X, k, tol )</b> 
<br>
<br><b>svds( mat U, vec s, mat V, sp_mat X, k )</b>
<br><b>svds( mat U, vec s, mat V, sp_mat X, k, tol )</b>
<br>
<br><b>svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k )</b>
<br><b>svds( cx_mat U, vec s, cx_mat V, sp_cx_mat X, k, tol )</b>
<ul>
<li>
Obtain a limited number of singular values and singular vectors (truncated SVD) of <b>sparse</b> matrix <i>X</i>
</li>
<br>
<li>
The singular values and vectors are calculated via sparse eigen decomposition of:
<code>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr><td>&#9121;&nbsp;</td><td>zeros(X.n_rows, X.n_rows)</td><td>&nbsp;</td><td>                          X</td><td>&nbsp;&#9124;</td></tr>
<tr><td>&#9123;&nbsp;</td><td style="text-align: right;">X.t()</td><td>&nbsp;</td><td>zeros(X.n_cols, X.n_cols)</td><td>&nbsp;&#9126;</td></tr> 
</tbody>
</table>
</code>
</li>
<br>
<li>
<i>k</i> specifies the number of singular values and singular vectors 
</li>
<br>
<li>
The singular values are in descending order
</li>
<br>
<li>
The argument <i>tol</i> is optional; it specifies the tolerance for convergence;
it is passed as <i>(tol&nbsp;&divide;&nbsp;&radic;2)</i> to <a href="#eigs_sym">eigs_sym()</a>
</li>
<br>
<li>
If the decomposition fails, the output objects are reset and:
<ul>
<li><i>s = svds(X,k)</i> resets <i>s</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>svds(s,X,k)</i> resets <i>s</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
<li><i>svds(U,s,V,X,k)</i> resets <i>U</i>, <i>s</i>, <i>V</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
<b>Caveats:</b>
<ul>
<li>
<i>svds()</i> is intended only for finding a few singular values from a large sparse matrix;
to find all singular values, use <a href="#svd">svd()</a> instead
</li>
<li>
depending on the given matrix, <i>svds()</i> may find fewer singular values than specified
</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
sp_mat X = sprandu&lt;sp_mat&gt;(100, 200, 0.1);

mat U;
vec s;
mat V;

svds(U, s, V, X, 10);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eigs_gen">eigs_gen()</a></li>
<li><a href="#eigs_sym">eigs_sym()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">singular value decomposition in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">singular value decomposition in MathWorld</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Signal &amp; Image Processing</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="conv"></a>
<b>conv( A, B )</b>
<br><b>conv( A, B, shape )</b>
<ul>
<li>
1D convolution of vectors <i>A</i> and <i>B</i>
</li>
<br>
<li>
The orientation of the result vector is the same as the orientation of <i>A</i> (ie. either column or row vector)
</li>
<br>
<li>
The <i>shape</i> argument is optional; it is one of:
<ul>
<ul>
<table>
<tbody>
<tr><td style="text-align: right;"><code>"full"</code></td><td>&nbsp;=&nbsp;</td><td>return the full convolution (<b>default setting</b>), with the size equal to <i>A.n_elem&nbsp;+&nbsp;B.n_elem&nbsp;-&nbsp;1</i></td></tr>
<tr><td style="text-align: right;"><code>"same"</code></td><td>&nbsp;=&nbsp;</td><td>return the central part of the convolution, with the same size as vector <i>A</i></td></tr>
</tbody>
</table>
</ul>
</ul>
</li>
<br>
<li>
The convolution operation is also equivalent to FIR filtering
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec A(256, fill::randu);

vec B(16, fill::randu);

vec C = conv(A, B);

vec D = conv(A, B, "same");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#conv2">conv2()</a></li>
<li><a href="#fft">fft()</a></li>
<li><a href="#cor">cor()</a></li>
<li><a href="#interp1">interp1()</a></li>
<li><a href="http://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Finite_impulse_response">FIR filter in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="conv2"></a>
<b>conv2( A, B )</b>
<br><b>conv2( A, B, shape )</b>
<ul>
<li>
2D convolution of matrices <i>A</i> and <i>B</i>
</li>
<br>
<li>
The <i>shape</i> argument is optional; it is one of:
<ul>
<ul>
<table>
<tbody>
<tr><td style="text-align: right;"><code>"full"</code></td><td>&nbsp;=&nbsp;</td><td>return the full convolution (<b>default setting</b>), with the size equal to <i>size(A)&nbsp;+&nbsp;size(B)&nbsp;-&nbsp;1</i></td></tr>
<tr><td style="text-align: right;"><code>"same"</code></td><td>&nbsp;=&nbsp;</td><td>return the central part of the convolution, with the same size as matrix <i>A</i></td></tr>
</tbody>
</table>
</ul>
</ul>
</li>
<br>
<li>The implementation of 2D convolution in this version is preliminary; it is not yet fully optimised</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(256, 256, fill::randu);

mat B(16, 16, fill::randu);

mat C = conv2(A, B);

mat D = conv2(A, B, "same");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#conv">conv()</a></li>
<li><a href="#fft2">fft2()</a></li>
<li><a href="#interp2">interp2()</a></li>
<li><a href="http://mathworld.wolfram.com/Convolution.html">Convolution in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Convolution">Convolution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Kernel_%28image_processing%29">Kernel (image processing) in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="fft"></a>
<b>cx_mat Y = &nbsp;fft( X )</b><br>
<b>cx_mat Y = &nbsp;fft( X, n )</b><br>
<br>
<b>cx_mat Z = ifft( cx_mat Y )</b><br>
<b>cx_mat Z = ifft( cx_mat Y, n )</b><br>
<ul>
<li><i>fft():</i> fast Fourier transform of a vector or matrix (real or complex)</li>
<br>
<li><i>ifft():</i> inverse fast Fourier transform of a vector or matrix (complex only)</li>
<br>
<li>If given a matrix, the transform is done on each column vector of the matrix</li>
<br>
<li>
The optional <i>n</i> argument specifies the transform length:
<ul>
<li>if <i>n</i> is larger than the length of the input vector, a zero-padded version of the vector is used</li>
<li>if <i>n</i> is smaller than the length of the input vector, only the first <i>n</i> elements of the vector are used</li>
</ul>
</li>
<br>
<li>
If <i>n</i> is not specified, the transform length is the same as the length of the input vector
</li>
<br>
<li><b>Caveat:</b> the transform is fastest when the transform length is a power of 2, eg. 64, 128, 256, 512, 1024, ...</li>
<br>
<li>The implementation of the transform in this version is preliminary; it is not yet fully optimised</li>
<br>
<li>
Examples:
<ul>
<pre>
   vec X(100, fill::randu);
   
cx_vec Y = fft(X, 128);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#fft2">fft2()</a></li>
<li><a href="#conv">conv()</a></li>
<li><a href="#imag_real">real()</a></li>
<li><a href="http://mathworld.wolfram.com/FastFourierTransform.html">fast Fourier transform in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Fast_Fourier_transform">fast Fourier transform in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="fft2"></a>
<b>cx_mat Y = &nbsp;fft2( X )</b><br>
<b>cx_mat Y = &nbsp;fft2( X, n_rows, n_cols )</b><br>
<br>
<b>cx_mat Z = ifft2( cx_mat Y )</b><br>
<b>cx_mat Z = ifft2( cx_mat Y, n_rows, n_cols )</b><br>
<ul>
<li><i>fft2():</i> 2D fast Fourier transform of a matrix (real or complex)</li>
<br>
<li><i>ifft2():</i> 2D inverse fast Fourier transform of a matrix (complex only)</li>
<br>
<li>
The optional arguments <i>n_rows</i> and <i>n_cols</i> specify the size of the transform;
a truncated and/or zero-padded version of the input matrix is used
</li>
<br>
<li><b>Caveat:</b> the transform is fastest when both <i>n_rows</i> and <i>n_cols</i> are a power of 2, eg. 64, 128, 256, 512, 1024, ...</li>
<br>
<li>The implementation of the transform in this version is preliminary; it is not yet fully optimised</li>
<br>
<li>
Examples:
<ul>
<pre>
   mat A(100, 100, fill::randu);
   
cx_mat B = fft2(A);
cx_mat C = fft2(A, 128, 128);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#fft">fft()</a></li>
<li><a href="#conv2">conv2()</a></li>
<li><a href="#imag_real">real()</a></li>
<li><a href="http://mathworld.wolfram.com/FastFourierTransform.html">fast Fourier transform in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Fast_Fourier_transform">fast Fourier transform in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="interp1"></a>
<b>interp1( X, Y, XI, YI )</b>
<br><b>interp1( X, Y, XI, YI, method )</b>
<br><b>interp1( X, Y, XI, YI, method, extrapolation_value )</b>
<ul>
<li>
1D data interpolation
</li>
<br>
<li>
Given a 1D function specified in vectors <i>X</i> and <i>Y</i>
(where <i>X</i> specifies locations and <i>Y</i> specifies the corresponding values),
<br>
generate vector <i>YI</i> which contains interpolated values at locations <i>XI</i>
</li>
<br>
<li>
The <i>method</i> argument is optional; it is one of:
<ul>
<table>
<tbody>
<tr><td style="text-align: right;"><code>"nearest"</code></td><td>&nbsp;=&nbsp;</td><td>interpolate using single nearest neighbour</td></tr>
<tr><td style="text-align: right;"><code>"linear"</code></td><td>&nbsp;=&nbsp;</td><td>linear interpolation between two nearest neighbours (<b>default setting</b>)</td></tr>
<tr><td style="text-align: right;"><code>"*nearest"</code></td><td>&nbsp;=&nbsp;</td><td>as per <code>"nearest"</code>, but faster by assuming that <i>X</i> and <i>XI</i> are monotonically increasing</td></tr>
<tr><td style="text-align: right;"><code>"*linear"</code></td><td>&nbsp;=&nbsp;</td><td>as per <code>"linear"</code>, but faster by assuming that <i>X</i> and <i>XI</i> are monotonically increasing</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
If a location in <i>XI</i> is outside the domain of <i>X</i>, the corresponding value in <i>YI</i> is set to <i>extrapolation_value</i>
</li>
<br>
<li>
The <i>extrapolation_value</i> argument is optional; by default it is <a href="#constants">datum::nan</a> (not-a-number)
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec x = linspace&lt;vec&gt;(0, 3, 20);
vec y = square(x);

vec xx = linspace&lt;vec&gt;(0, 3, 100);

vec yy;

interp1(x, y, xx, yy);  // use linear interpolation by default

interp1(x, y, xx, yy, "*linear");  // faster than "linear"

interp1(x, y, xx, yy, "nearest");
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#interp2">interp2()</a></li>
<li><a href="#polyval">polyval()</a></li>
<li><a href="#linspace">linspace()</a></li>
<li><a href="#regspace">regspace()</a></li>
<li><a href="#conv">conv()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Interpolation">interpolation in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="interp2"></a>
<b>interp2( X, Y, Z, XI, YI, ZI )</b>
<br><b>interp2( X, Y, Z, XI, YI, ZI, method )</b>
<br><b>interp2( X, Y, Z, XI, YI, ZI, method, extrapolation_value )</b>
<ul>
<li>
2D data interpolation
</li>
<br>
<li>
Given a 2D function specified by matrix <i>Z</i> with coordinates given by vectors <i>X</i> and <i>Y</i>,
<br>generate matrix <i>ZI</i> which contains interpolated values at the coordinates given by vectors <i>XI</i> and <i>YI</i>
</li>
<br>
<li>
The vector pairs <i>(X,&nbsp;Y)</i> and <i>(XI,&nbsp;YI)</i> define 2D coordinates in a grid;
<br>for example, <i>X</i> defines the horizontal coordinates and <i>Y</i> defines the corresponding vertical coordinates,
<br>so that (&nbsp;<i>X(m)</i>,&nbsp;<i>Y(n)&nbsp;)</i> is the 2D coordinate of element <i>Z(n,m)</i>
</li>
<br>
<li>
The length of vector <i>X</i> must be equal to the number of columns in matrix <i>Z</i>
</li>
<br>
<li>
The length of vector <i>Y</i> must be equal to the number of rows in matrix <i>Z</i>
</li>
<br>
<li>
Vectors <i>X</i>, <i>Y</i>, <i>XI</i>, <i>YI</i> must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)
</li>
<br>
<li>
The <i>method</i> argument is optional; it is one of:
<ul>
<table>
<tbody>
<tr><td style="text-align: right;"><code>"nearest"</code></td><td>&nbsp;=&nbsp;</td><td>interpolate using nearest neighbours</td></tr>
<tr><td style="text-align: right;"><code>"linear"</code></td><td>&nbsp;=&nbsp;</td><td>linear interpolation between nearest neighbours (<b>default setting</b>)</td></tr>
</tbody>
</table>
</ul>
</li>
<br>
<li>
If a coordinate in the 2D grid specified by <i>(XI,&nbsp;YI)</i> is outside the domain of the 2D grid specified by <i>(X,&nbsp;Y)</i>,
<br>the corresponding value in <i>ZI</i> is set to <i>extrapolation_value</i>
</li>
<br>
<li>
The <i>extrapolation_value</i> argument is optional; by default it is <a href="#constants">datum::nan</a> (not-a-number)
</li>
<br>
<li>
Examples:
<ul>
<pre>

mat Z;

Z.load("input_image.pgm", pgm_binary);  // load an image in pgm format

vec X = regspace(1, Z.n_cols);  // X = horizontal spacing
vec Y = regspace(1, Z.n_rows);  // Y = vertical spacing

vec XI = regspace(X.min(), 1.0/2.0, X.max()); // magnify by approx 2
vec YI = regspace(Y.min(), 1.0/3.0, Y.max()); // magnify by approx 3

mat ZI;

interp2(X, Y, Z, XI, YI, ZI);  // use linear interpolation by default

ZI.save("output_image.pgm", pgm_binary);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#interp1">interp1()</a></li>
<li><a href="#regspace">regspace()</a></li>
<li><a href="#conv2">conv2()</a></li>
<li><a href="#reshape">reshape()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Bilinear_interpolation">bilinear interpolation in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="polyfit"></a>
<b>P = polyfit( X, Y, N )</b>
<br><b>polyfit( P, X, Y, N )</b>
<ul>
<li>
Given a 1D function specified in vectors <i>X</i> and <i>Y</i>
(where <i>X</i> holds independent values and <i>Y</i> holds the corresponding dependent values),
<br>model the function as a polynomial of order <i>N</i> and store the polynomial coefficients in column vector <i>P</i>
</li>
<br>
<li>
The given function is modelled as:
<ul>
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
  + p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
  + p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
  + ...
  + p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
  + p<sub><sub>N</sub></sub>
</ul>
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient; the coefficients are selected to minimise the overall error of the fit (least squares)
</li>
<br>
<li>
The column vector <i>P</i> has <i>N+1</i> coefficients
</li>
<br>
<li>
<i>N</i> must be smaller than the number of elements in <i>X</i>
</li>
<br>
<li>If the polynomial coefficients cannot be found:
<ul>
<li><i>P = polyfit( X, Y, N )</i> resets <i>P</i> and throws a <i>std::runtime_error</i> exception</li>
<li><i>polyfit( P, X, Y, N )</i> resets <i>P</i> and returns a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec x = linspace&lt;vec&gt;(0,4*datum::pi,100);
vec y = cos(x);

vec p = polyfit(x,y,10);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#polyval">polyval()</a></li>
<li><a href="#roots">roots()</a></li>
<li><a href="#interp1">interp1()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Polynomial">polynomial in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Least_squares">least squares in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Curve_fitting">curve fitting in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/LeastSquaresFitting.html">least squares fitting in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="polyval"></a>
<b>Y = polyval( P, X )</b>
<ul>
<li>
Given vector <i>P</i> of polynomial coefficients and vector <i>X</i> containing the independent values of a 1D function,
<br>generate vector <i>Y</i> which contains the corresponding dependent values
</li>
<br>
<li>
For each <i>x</i> value in vector <i>X</i>, the corresponding <i>y</i> value in vector <i>Y</i> is generated using:
<ul>
y = p<sub><sub>0</sub></sub>x<sup><sup>N</sup></sup>
  + p<sub><sub>1</sub></sub>x<sup><sup>N-1</sup></sup>
  + p<sub><sub>2</sub></sub>x<sup><sup>N-2</sup></sup>
  + ...
  + p<sub><sub>N-1</sub></sub>x<sup><sup>1</sup></sup>
  + p<sub><sub>N</sub></sub>
</ul>
where p<sub><sub>i</sub></sub> is the i-th polynomial coefficient in vector <i>P</i>
</li>
<br>
<li>
<i>P</i> must contain polynomial coefficients in descending powers (eg. generated by the <a href="#polyfit">polyfit()</a> function)
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec x1 = linspace&lt;vec&gt;(0,4*datum::pi,100);
vec y1 = cos(x1);
vec p1 = polyfit(x1,y1,10);

vec y2 = polyval(p1,x1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#polyfit">polyfit()</a></li>
<li><a href="#roots">roots()</a></li>
<li><a href="#interp1">interp1()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Polynomial">polynomial in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Statistics &amp; Clustering</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="stats_fns"></a>
<b>mean, median, stddev, var, range</b>
<ul>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tbody>
  <tr>
    <td style="vertical-align: top;">
       <b>mean( V )</b>
       <br><b>mean( M )</b>
       <br><b>mean( M, dim )</b>
       <br><b>mean( Q )</b>
       <br><b>mean( Q, dim )</b>
       <br>
       <br>
    </td>
    <td style="vertical-align: top;">
      &nbsp;&nbsp;&nbsp;
    </td>
    <td style="vertical-align: top;">
      &#9131;&nbsp;<br>
      &#9130;&nbsp;<br>
      &#9132;&nbsp;&nbsp;mean (average value)<br>
      &#9130;&nbsp;<br>
      &#9133;&nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
       <b>median( V )</b>
       <br><b>median( M )</b>
       <br><b>median( M, dim )</b>
       <br>
       <br>
    </td>
    <td style="vertical-align: top;">
      &nbsp;&nbsp;&nbsp;
    </td>
    <td style="vertical-align: top;">
      &#9131;&nbsp;<br>
      &#9132;&nbsp;&nbsp;median<br>
      &#9133;&nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
       <b>stddev( V )</b>
       <br><b>stddev( V, norm_type )</b>
       <br><b>stddev( M )</b>
       <br><b>stddev( M, norm_type )</b>
       <br><b>stddev( M, norm_type, dim )</b>
       <br>
       <br>
    </td>
    <td style="vertical-align: top;">
      &nbsp;&nbsp;&nbsp;
    </td>
    <td style="vertical-align: top;">
      &#9131;&nbsp;<br>
      &#9130;&nbsp;<br>
      &#9132;&nbsp;&nbsp;standard deviation<br>
      &#9130;&nbsp;<br>
      &#9133;&nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
       <b>var( V )</b>
       <br><b>var( V, norm_type )</b>
       <br><b>var( M )</b>
       <br><b>var( M, norm_type )</b>
       <br><b>var( M, norm_type, dim )</b>
       <br>
       <br>
    </td>
    <td style="vertical-align: top;">
      &nbsp;&nbsp;&nbsp;
    </td>
    <td style="vertical-align: top;">
      &#9131;&nbsp;<br>
      &#9130;&nbsp;<br>
      &#9132;&nbsp;&nbsp;variance<br>
      &#9130;&nbsp;<br>
      &#9133;&nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
       <b>range( V )</b>
       <br><b>range( M )</b>
       <br><b>range( M, dim )</b>
       <br>
       <br>
    </td>
    <td style="vertical-align: top;">
      &nbsp;&nbsp;&nbsp;
    </td>
    <td style="vertical-align: top;">
      &#9131;&nbsp;<br>
      &#9132;&nbsp;&nbsp;range (difference between max and min)<br>
      &#9133;&nbsp;
    </td>
  </tr>
</tbody>
</table>
<li>
For vector <i>V</i>, return the statistic calculated using all the elements of the vector
</li>
<br>
<li>
For matrix <i>M</i>, find the statistic for each column (<i>dim=0</i>), or each row (<i>dim=1</i>)
</li>
<br>
<li>
For cube <i>Q</i>, find the statistics of elements along dimension <i>dim</i>, where <i>dim</i> &isin; {&nbsp;0,&nbsp;1,&nbsp;2&nbsp;}
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i> is used
</li>
<br>
<li>
The <i>norm_type</i> argument is optional; by default <i>norm_type=0</i> is used
</li>
<br>
<li>
For the <i>var()</i> and <i>stddev()</i> functions:
<ul>
<li>the default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of samples), providing the best unbiased estimator</li>
<li>using <i>norm_type=1</i> performs normalisation using <i>N</i>, which provides the second moment around the mean</li>
</ul>
</li>
<br>
<li>
<b>Caveat:</b>
to obtain statistics for integer matrices/vectors (eg. <a href="#Mat">umat</a>, <a href="#Mat">imat</a>, <a href="#Col">uvec</a>, <a href="#Col">ivec</a>),
convert to a matrix/vector with floating point values (eg. <a href="#Mat">mat</a>, <a href="#Col">vec</a>) using the <a href="#conv_to">conv_to()</a> function
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 5, fill::randu);

mat B    = mean(A);
mat C    = var(A);
double m = mean(mean(A));

vec v(5, fill::randu);
double x = var(v);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cov">cov()</a></li>
<li><a href="#cor">cor()</a></li>
<li><a href="#diff">diff()</a></li>
<li><a href="#hist">hist()</a></li>
<li><a href="#histc">histc()</a></li>
<li><a href="#quantile">quantile()</a></li>
<li><a href="#min_and_max">min() &amp; max()</a></li>
<li><a href="#running_stat">running_stat</a> - class for running statistics of scalars</li>
<li><a href="#running_stat_vec">running_stat_vec</a> - class for running statistics of vectors</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#kmeans">kmeans()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cov"></a>
<b>cov( X, Y )</b>
<br><b>cov( X, Y, norm_type )</b>
<br>
<br><b>cov( X )</b>
<br><b>cov( X, norm_type )</b>
<ul>
<li>
For two matrix arguments <i>X</i> and <i>Y</i>,
if each row of <i>X</i> and <i>Y</i>  is an observation and each column is a variable,
the <i>(i,j)</i>-th entry of <i>cov(X,Y)</i> is the covariance between the <i>i</i>-th variable in <i>X</i> and the <i>j</i>-th variable in <i>Y</i>
</li>
<br>
<li>
For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation
</li>
<br>
<li>
For matrices, <i>X</i> and <i>Y</i> must have the same dimensions
</li>
<br>
<li>
For vectors, <i>X</i> and <i>Y</i> must have the same number of elements
</li>
<br>
<li>
<i>cov(X)</i> is equivalent to <i>cov(X, X)</i>
</li>
<br>
<li>
The default <i>norm_type=0</i> performs normalisation using <i>N-1</i> (where <i>N</i> is the number of observations),
providing the best unbiased estimation of the covariance matrix (if the observations are from a normal distribution).
Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment matrix of the observations about their mean
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4, 5, fill::randu);
mat Y(4, 5, fill::randu);

mat C = cov(X,Y);
mat D = cov(X,Y, 1);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#cor">cor()</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
<li><a href="http://mathworld.wolfram.com/Covariance.html">Covariance in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cor"></a>
<b>cor( X, Y )</b>
<br><b>cor( X, Y, norm_type )</b>
<br>
<br><b>cor( X )</b>
<br><b>cor( X, norm_type )</b>
<ul>
<li>
For two matrix arguments <i>X</i> and <i>Y</i>,
if each row of <i>X</i> and <i>Y</i>  is an observation and each column is a variable,
the <i>(i,j)</i>-th entry of <i>cor(X,Y)</i> is the correlation coefficient between the <i>i</i>-th variable in <i>X</i> and the <i>j</i>-th variable in <i>Y</i>
</li>
<br>
<li>
For vector arguments, the type of vector is ignored and each element in the vector is treated as an observation 
</li>
<br>
<li>
For matrices, <i>X</i> and <i>Y</i> must have the same dimensions
</li>
<br>
<li>
For vectors, <i>X</i> and <i>Y</i> must have the same number of elements
</li>
<br>
<li>
<i>cor(X)</i> is equivalent to <i>cor(X, X)</i>
</li>
<br>
<li>
The default <i>norm_type=0</i> performs normalisation of the correlation matrix using <i>N-1</i> (where <i>N</i> is the number of observations).
Using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(4, 5, fill::randu);
mat Y(4, 5, fill::randu);

mat R = cor(X,Y);
mat S = cor(X,Y, 1);
</pre>
</ul>
</li>
<br>
<li>
See also: 
<ul>
<li><a href="#cov">cov()</a></li>
<li><a href="#conv">conv()</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
<li><a href="http://mathworld.wolfram.com/Correlation.html">Correlation in MathWorld</a></li>
<li><a href="http://mathworld.wolfram.com/Autocorrelation.html">Autocorrelation in MathWorld</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="hist"></a>
<b>hist( V )</b>
<br><b>hist( V, n_bins )</b>
<br><b>hist( V, centers )</b>
<br>
<br><b>hist( X, centers )</b>
<br><b>hist( X, centers, dim )</b>
<ul>
<li>
For vector <i>V</i>,
produce an unsigned vector of the same orientation as <i>V</i> (ie. either <a href="#Col">uvec</a> or <a href="#Row">urowvec</a>)
that represents a histogram of counts
</li>
<br>
<li>
For matrix <i>X</i>,
produce a <a href="#Mat">umat</a> matrix containing either
column histogram counts (for <i>dim=0</i>, default),
or
row histogram counts (for <i>dim=1</i>)
</li>
<br>
<li>
The bin centers can be automatically determined from the data, with the number of bins specified via <i>n_bins</i> (default is 10);
the range of the bins is determined by the range of the data
</li>
<br>
<li>
The bin centers can also be explicitly specified via the <i>centers</i> vector;
the vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)
</li>
<br>
<li>
Examples:
<ul>
<pre>
 vec v(1000, fill::randn); // Gaussian distribution

uvec h1 = hist(v, 11);
uvec h2 = hist(v, linspace&lt;vec&gt;(-2,2,11));
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#histc">histc()</a></li>
<li><a href="#quantile">quantile()</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#conv_to">conv_to()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="histc"></a>
<b>histc( V, edges )</b>
<br><b>histc( X, edges )</b>
<br><b>histc( X, edges, dim )</b>
<ul>
<li>
For vector <i>V</i>,
produce an unsigned vector of the same orientation as <i>V</i> (ie. either <a href="#Col">uvec</a> or <a href="#Row">urowvec</a>)
that contains the counts of the number of values that fall between the elements in the <i>edges</i> vector
</li>
<br>
<li>
For matrix <i>X</i>,
produce a <i>umat</i> matrix containing either
column histogram counts (for <i>dim=0</i>, default),
or
row histogram counts (for <i>dim=1</i>)
</li>
<br>
<li>
The <i>edges</i> vector must contain monotonically increasing values (eg. 0.1, 0.2, 0.3, ...)
</li>
<br>
<li>
Examples:
<ul>
<pre>
 vec v(1000, fill::randn);  // Gaussian distribution

uvec h = histc(v, linspace&lt;vec&gt;(-2,2,11));
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#hist">hist()</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#conv_to">conv_to()</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="quantile"></a>
<b>quantile( V, P )</b>
<br><b>quantile( X, P )</b>
<br><b>quantile( X, P, dim )</b>
<ul>
<li>
For a dataset stored in vector <i>V</i> or matrix <i>X</i>,
calculate the quantiles corresponding to the cumulative probability values in the given <i>P</i> vector
</li>
<br>
<li>
For vector <i>V</i>, produce a vector with the same orientation as <i>V</i> and the same length as <i>P</i>
</li>
<br>
<li>
For matrix <i>X</i>, produce a matrix with the quantiles for each column vector (<i>dim=0</i>) or each row vector (<i>dim=0</i>)
</li>
<br>
<li>
The <i>dim</i> argument is optional; by default <i>dim=0</i>
</li>
<br>
<li>
The <i>P</i> vector must contain values in the [0,1] interval (eg. 0.00, 0.25, 0.50, 0.75, 1.00)
</li>
<br>
<li>
The algorithm for calculating the quantiles is based on <i>Definition 5</i> in:
<br>
Rob J. Hyndman and Yanan Fan.
Sample Quantiles in Statistical Packages.
The American Statistician, Vol. 50, No. 4, pp. 361-365, 1996.
<a href="http://doi.org/10.2307/2684934">http://doi.org/10.2307/2684934</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec V(1000, fill::randn);  // Gaussian distribution

vec P = { 0.25, 0.50, 0.75 };

vec Q = quantile(V, P);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#hist">hist()</a></li>
<li><a href="#stats_fns">median()</a></li>
<li><a href="#normcdf">normcdf()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Quantile">quantile in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="princomp"></a>
<b>mat coeff = princomp( mat X )</b>
<br><b>cx_mat coeff = princomp( cx_mat X )</b><br>

<br><b>princomp( mat coeff, mat X )</b>
<br><b>princomp( cx_mat coeff, cx_mat X )</b><br>

<br><b>princomp( mat coeff, mat score, mat X )</b>
<br><b>princomp( cx_mat coeff, cx_mat score, cx_mat X )</b><br>

<br><b>princomp( mat coeff, mat score, vec latent, mat X )</b>
<br><b>princomp( cx_mat coeff, cx_mat score, vec latent, cx_mat X )</b><br>

<br><b>princomp( mat coeff, mat score, vec latent, vec tsquared, mat X )</b>
<br><b>princomp( cx_mat coeff, cx_mat score, vec latent, cx_vec tsquared, cx_mat X )</b><br>
<ul>
<li>Principal component analysis of matrix <i>X</i></li><br>
<li>Each row of <i>X</i> is an observation and each column is a variable</li><br>
<li>output objects:
<ul>
<li><i>coeff</i>: principal component coefficients</li>
<li><i>score</i>: projected data</li>
<li><i>latent</i>: eigenvalues of the covariance matrix of <i>X</i></li>
<li><i>tsquared</i>: Hotteling's statistic for each sample</li>
</ul>
</li>
<br>
<li>
The computation is based on singular value decomposition
</li>
<br>
<li>If the decomposition fails:
<ul>
<li><i>coeff = princomp(X)</i> resets <i>coeff</i> and throws a <i>std::runtime_error</i> exception</li>
<li>remaining forms of <i>princomp()</i> reset all output matrices and return a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat A(5, 4, fill::randu);

mat coeff;
mat score;
vec latent;
vec tsquared;

princomp(coeff, score, latent, tsquared, A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#eig_sym">eig_sym()</a></li>
<li><a href="#svd">svd()</a></li>
<li><a href="#svd_econ">svd_econ()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Principal_component_analysis">principal components analysis in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="normpdf"></a>
<b>normpdf( X )</b>
<br><b>normpdf( X, M, S )</b>
<ul>
<li>
For each scalar <i>x</i> in <i>X</i>, compute its probability density function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>:
<br>
<br>
<ul>
<code>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td>&nbsp;</td><td>&nbsp;&nbsp;&nbsp;1</td><td>&nbsp;</td><td>&#9127;</td><td>&nbsp;</td><td>(x-m)<sup>2</sup></td><td>&#9131;</td>
    </tr>
    <tr>
      <td>y&nbsp;=&nbsp;</td><td>&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;</td><td>&nbsp;exp</td><td>&#9130;</td><td>&minus;0.5&nbsp;</td><td>&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;&nbsp;</td><td>&#9130;</td>
    </tr>
    <tr>
      <td>&nbsp;</td><td>s&nbsp;&radic;(2&pi;)</td><td>&nbsp;</td><td>&#9129;</td><td>&nbsp;</td><td>&nbsp;&nbsp;s<sup>2</sup></td><td>&#9133;</td>
    </tr>
  </tbody>
</table>
</code>
</ul>
</li>
<br>
<li><i>X</i> can be a scalar, vector, or matrix</li>
<br>
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
<br>
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
<br>
<li>
<b>Caveat:</b> to reduce the incidence of numerical underflows, consider using <a href="#log_normpdf">log_normpdf()</a>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec X(10, fill::randu);
vec M(10, fill::randu);
vec S(10, fill::randu);

   vec P1 = normpdf(X);
   vec P2 = normpdf(X,    M,    S   );
   vec P3 = normpdf(1.23, M,    S   );
   vec P4 = normpdf(X,    4.56, 7.89);
double P5 = normpdf(1.23, 4.56, 7.89);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#log_normpdf">log_normpdf()</a></li>
<li><a href="#normcdf">normcdf()</a></li>
<li><a href="#randu_randn_standalone">randn()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="log_normpdf"></a>
<b>log_normpdf( X )</b>
<br><b>log_normpdf( X, M, S )</b>
<ul>
<li>
For each scalar <i>x</i> in <i>X</i>, compute the logarithm version of probability density function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>:
<br>
<br>
<ul>
<code>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td>&nbsp;</td><td>&nbsp;</td><td>&#9127;</td><td>&nbsp;&nbsp;&nbsp;1</td><td>&nbsp;</td><td>&#9127;</td><td>&nbsp;</td><td>(x-m)<sup>2</sup></td><td>&#9131;</td><td>&#9131;</td>
    </tr>
    <tr>
      <td>y&nbsp;=&nbsp;</td><td>log</td><td>&#9130;</td><td>&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;</td><td>&nbsp;exp</td><td>&#9130;</td><td>&minus;0.5&nbsp;</td><td>&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;&nbsp;</td><td>&#9130;</td><td>&#9130;</td>
    </tr>
    <tr>
      <td>&nbsp;</td><td>&nbsp;</td><td>&#9129;</td><td>s&nbsp;&radic;(2&pi;)</td><td>&nbsp;</td><td>&#9129;</td><td>&nbsp;</td><td>&nbsp;&nbsp;s<sup>2</sup></td><td>&#9133;</td><td>&#9133;</td>
    </tr>
  </tbody>
</table>
<br>
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&#9127;</td><td>&nbsp;</td><td>(x-m)<sup>2</sup></td><td>&#9131;</td>
    </tr>
    <tr>
      <td>&nbsp;&nbsp;=&nbsp;</td><td>&minus;log(s&nbsp;&radic;(2&pi;))</td><td>&nbsp;&plus;&nbsp;</td><td>&#9130;</td><td>&minus;0.5&nbsp;</td><td>&#8210;&#8210;&#8210;&#8210;&#8210;&#8210;&nbsp;</td><td>&#9130;</td>
    </tr>
    <tr>
      <td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&#9129;</td><td>&nbsp;</td><td>&nbsp;&nbsp;s<sup>2</sup></td><td>&#9133;</td>
    </tr>
  </tbody>
</table>
</code>
</ul>
</li>
<br>
<li><i>X</i> can be a scalar, vector, or matrix</li>
<br>
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
<br>
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
<br>
<li>
Examples:
<ul>
<pre>
vec X(10, fill::randu);
vec M(10, fill::randu);
vec S(10, fill::randu);

   vec P1 = log_normpdf(X);
   vec P2 = log_normpdf(X,    M,    S   );
   vec P3 = log_normpdf(1.23, M,    S   );
   vec P4 = log_normpdf(X,    4.56, 7.89);
double P5 = log_normpdf(1.23, 4.56, 7.89);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="normcdf"></a>
<b>normcdf( X )</b>
<br><b>normcdf( X, M, S )</b>
<ul>
<li>
For each scalar <i>x</i> in <i>X</i>, compute its cumulative distribution function according to a Gaussian (normal) distribution using the corresponding mean value <i>m</i> in <i>M</i> and the corresponding standard deviation value <i>s</i> in <i>S</i>
</li>
<br>
<li><i>X</i> can be a scalar, vector, or matrix</li>
<br>
<li><i>M</i> and <i>S</i> can jointly be either scalars, vectors, or matrices</li>
<br>
<li>If <i>M</i> and <i>S</i> are omitted, their values are assumed to be 0 and 1, respectively</li>
<br>
<li>
Examples:
<ul>
<pre>
vec X(10, fill::randu);
vec M(10, fill::randu);
vec S(10, fill::randu);

   vec P1 = normcdf(X);
   vec P2 = normcdf(X,    M,    S   );
   vec P3 = normcdf(1.23, M,    S   );
   vec P4 = normcdf(X,    4.56, 7.89);
double P5 = normcdf(1.23, 4.56, 7.89);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#quantile">quantile()</a></li>
<li><a href="#randu_randn_standalone">randn()</a></li>
<li><a href="http://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/Cumulative_distribution_function">cumulative distribution function in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="mvnrnd"></a>
<b>X = mvnrnd( M, C )</b>
<br><b>X = mvnrnd( M, C, N )</b>
<br>
<br>
<b>mvnrnd( X, M, C )</b>
<br><b>mvnrnd( X, M, C, N )</b>
<ul>
<li>
Generate a matrix with random column vectors from a multivariate Gaussian (normal) distribution with parameters <i>M</i> and <i>C</i>:
<ul>
<li><i>M</i> is the mean; must be a column vector</li>
<li><i>C</i> is the covariance matrix; must be symmetric positive semi-definite (preferably positive definite)</li>
</ul>
</li>
<br>
<li><i>N</i> is the number of column vectors to generate; if <i>N</i> is omitted, it is assumed to be 1</li>
<br>
<li>
<b>Caveat:</b> repeated generation of one vector (or a small number of vectors) using the same <i>M</i> and <i>C</i> parameters can be inefficient;
<br>for repeated generation consider using the <i>generate()</i> function in the <a href="#gmm_diag">gmm_diag</a> and <a href="#gmm_full">gmm_full</a> classes
</li>
<br>
<li>If generating the random vectors fails:
<ul>
<li><i>X = mvnrnd(M, C)</i> and <i>X = mvnrnd(M, C, N)</i> reset <i>X</i> and throw a <i>std::runtime_error</i> exception</li>
<li><i>mvnrnd(X, M, C)</i> and <i>mvnrnd(X, M, C, N)</i> reset <i>X</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
vec M(5, fill::randu);

mat B(5, 5, fill::randu);
mat C = B.t() * B;

mat X = mvnrnd(M, C, 100);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#randu_randn_standalone">randn()</a></li>
<li><a href="#chi2rnd">chi2rnd()</a></li>
<li><a href="#wishrnd">wishrnd()</a></li>
<li><a href="#cov">cov()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="https://en.wikipedia.org/wiki/Multivariate_normal_distribution">multivariate normal distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="chi2rnd"></a>
<b>chi2rnd( DF )</b>
<br>
<b>chi2rnd( DF_scalar )</b>
<br>
<b>chi2rnd( DF_scalar, n_elem )</b>
<br>
<b>chi2rnd( DF_scalar, n_rows, n_cols )</b>
<br>
<b>chi2rnd( DF_scalar, size(X) )</b>
<br>
<ul>
<li>
Generate a random scalar, vector or matrix with elements sampled from a chi-squared distribution with the degrees of freedom specified by parameter <i>DF</i> or <i>DF_scalar</i>
</li>
<br>
<li><i>DF</i> is a vector or matrix, while <i>DF_scalar</i> is a scalar</li>
<br>
<li>Each value in <i>DF</i> and <i>DF_scalar</i> must be greater than zero</li>
<br>
<li>
For the <i>chi2rnd(DF)</i> form, the output vector/matrix has the same size and type as <i>DF</i>; each element in <i>DF</i> specifies a separate degree of freedom
</li>
<br>
<li>
Usage:
<ul>
<li><i>vector_type</i> v = chi2rnd( DF ), where the type of DF is a real <i>vector_type</i></li>
<li><i>matrix_type</i> X = chi2rnd( DF ), where the type of DF is a real <i>matrix_type</i></li>
<br>
<li><i>scalar_type</i> s = chi2rnd&lt;<i>scalar_type</i>&gt;( DF_scalar ), where <i>scalar_type</i> is either <i>float</i> or <i>double</i></li>
<li><i>vector_type</i> v = chi2rnd&lt;<i>vector_type</i>&gt;( DF_scalar, n_elem )</li>
<li><i>matrix_type</i> X = chi2rnd&lt;<i>matrix_type</i>&gt;( DF_scalar, n_rows, n_cols )</li>
<li><i>matrix_type</i> Y = chi2rnd&lt;<i>matrix_type</i>&gt;( DF_scalar, size(X) )</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X = chi2rnd(2, 5, 6);

mat A = randi&lt;mat&gt;(5, 6, distr_param(1, 10));
mat B = chi2rnd(A);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#randg">randg()</a></li>
<li><a href="#randu_randn_standalone">randn()</a></li>
<li><a href="#mvnrnd">mvnrnd()</a></li>
<li><a href="#wishrnd">wishrnd()</a></li>
<li><a href="#size">size()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Chi-squared_distribution">chi-squared distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="wishrnd"></a>
<b>W = wishrnd( S, df )</b>
<br>
<b>W = wishrnd( S, df, D )</b>
<br>
<br>
<b>wishrnd( W, S, df )</b>
<br>
<b>wishrnd( W, S, df, D )</b>
<ul>
<li>
Generate a random matrix sampled from the Wishart distribution with parameters <i>S</i> and <i>df</i>:
<ul>
<li><i>S</i> is a symmetric positive definite matrix (eg. a covariance matrix)</li>
<li><i>df</i> is a scalar specifying the degrees of freedom; it can be a non-integer value</li>
</ul>
</li>
<br>
<li>
<i>D</i> is an optional argument; it specifies the Cholesky decomposition of <i>S</i>; if <i>D</i> is provided, <i>S</i> is ignored;
<br>using <i>D</i> is more efficient if you need to use <i>wishrnd()</i> many times for the same <i>S</i> matrix
</li>
<br>
<li>If generating the random matrix fails:
<ul>
<li><i>W = wishrnd(S, df)</i> and <i>W = wishrnd(S, df, D)</i> reset <i>W</i> and throw a <i>std::runtime_error</i> exception</li>
<li><i>wishrnd(W, S, df)</i> and <i>wishrnd(W, S, df, D)</i> reset <i>W</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);

mat S = X.t() * X;

mat W = wishrnd(S, 6.7);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#iwishrnd">iwishrnd()</a></li>
<li><a href="#chi2rnd">chi2rnd()</a></li>
<li><a href="#mvnrnd">mvnrnd()</a></li>
<li><a href="#chol">chol()</a></li>
<li><a href="#cov">cov()</a></li>
<li><a href="#randu_randn_standalone">randn()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Wishart_distribution">Wishart distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="iwishrnd"></a>
<b>W = iwishrnd( T, df )</b>
<br>
<b>W = iwishrnd( T, df, Dinv )</b>
<br>
<br>
<b>iwishrnd( W, T, df )</b>
<br>
<b>iwishrnd( W, T, df, Dinv )</b>
<ul>
<li>
Generate a random matrix sampled from the inverse Wishart distribution with parameters <i>T</i> and <i>df</i>:
<ul>
<li><i>T</i> is a symmetric positive definite matrix</li>
<li><i>df</i> is a scalar specifying the degrees of freedom; it can be a non-integer value</li>
</ul>
</li>
<br>
<li>
<i>Dinv</i> is an optional argument; it specifies the Cholesky decomposition of the inverse of <i>T</i>; if <i>Dinv</i> is provided, <i>T</i> is ignored
<br>using <i>Dinv</i> is more efficient if you need to use <i>iwishrnd()</i> many times for the same <i>T</i> matrix
</li>
<br>
<li>If generating the random matrix fails:
<ul>
<li><i>W = iwishrnd(T, df)</i> and <i>W = iwishrnd(T, df, Dinv)</i> reset <i>W</i> and throw a <i>std::runtime_error</i> exception</li>
<li><i>iwishrnd(W, T, df)</i> and <i>iwishrnd(W, T, df, Dinv)</i> reset <i>W</i> and return a bool set to <i>false</i> (exception is not thrown)</li>
</ul>
</li>
<br>
<li>
Examples:
<ul>
<pre>
mat X(5, 5, fill::randu);

mat T = X.t() * X;

mat W = iwishrnd(T, 6.7);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#wishrnd">wishrnd()</a></li>
<li><a href="#chol">chol()</a></li>
<li><a href="#inv_sympd">inv_sympd()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Inverse-Wishart_distribution">inverse Wishart distribution in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="running_stat"></a>
<b>running_stat&lt;</b><i>type</i><b>&gt;</b>
<ul>
<li>
Class for running statistics (online statistics) of scalars (one dimensional process/signal)
</li>
<br>
<li>
Useful if the storage of all samples (scalars) is impractical, or if the number of samples is not known in advance
</li>
<br>
<li>
<i>type</i> is one of: <i>float</i>, <i>double</i>, <i><a href="#cx_double">cx_float</a></i>, <i><a href="#cx_double">cx_double</a></i>
</li>
<br>
<li>
For an instance of <i>running_stat</i> named as <i>X</i>, the member functions are:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>X(</b>scalar<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      update the statistics using the given scalar
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.min()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current minimum value
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.max()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current maximum value
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.range()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current range
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.mean()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current mean or average value
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.var()</b> &nbsp;and&nbsp; <b>X.var(</b>norm_type<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current variance
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.stddev()</b> &nbsp;and&nbsp; <b>X.stddev(</b>norm_type<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current standard deviation
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.reset()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      reset all statistics and set the number of samples to zero
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.count()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current number of samples
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>norm_type</i> argument is optional; by default <i>norm_type=0</i> is used
</li>
<br>
<li>
For the <i>.var()</i> and <i>.stddev()</i> functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i>
(where <i>N</i> is the number of samples so far),
providing the best unbiased estimator;
using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean
</li>
<br>
<li>
The return type of <i>.count()</i> depends on the underlying form of <i>type</i>: it is either <i>float</i> or <i>double</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
running_stat&lt;double&gt; stats;

for(uword i=0; i&lt;10000; ++i)
  {
  double sample = randn();
  stats(sample);
  }

cout &lt;&lt; "mean = " &lt;&lt; stats.mean() &lt;&lt; endl;
cout &lt;&lt; "var  = " &lt;&lt; stats.var()  &lt;&lt; endl;
cout &lt;&lt; "min  = " &lt;&lt; stats.min()  &lt;&lt; endl;
cout &lt;&lt; "max  = " &lt;&lt; stats.max()  &lt;&lt; endl;
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#running_stat_vec">running_stat_vec</a> (running statistics of vectors)</li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="running_stat_vec"></a>
<b>running_stat_vec&lt;</b><i>vec_type</i><b>&gt;</b>
<br><b>running_stat_vec&lt;</b><i>vec_type</i><b>&gt;(calc_cov)</b>
<ul>
<li>
Class for running statistics (online statistics) of vectors (multi-dimensional process/signal)
</li>
<br>
<li>
Useful if the storage of all samples (vectors) is impractical, or if the number of samples is not known in advance
</li>
<br>
<li>
This class is similar to <i>running_stat</i>, with the difference that vectors are processed instead of scalars
</li>
<br>
<li>
<i>vec_type</i> is the vector type of the samples; for example: <i><a href="#Col">vec</a></i>, <i><a href="#Col">cx_vec</a></i>, <i><a href="#Row">rowvec</a></i>, ...
</li>
<br>
<li>
For an instance of <i>running_stat_vec</i> named as <i>X</i>, the member functions are:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>X(</b>vector<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      update the statistics using the given vector
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.min()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current minimum values
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.max()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current maximum values
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.range()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current ranges
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.mean()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current means
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.var()</b> &nbsp;and&nbsp; <b>X.var(</b>norm_type<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current variances
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.stddev()</b> &nbsp;and&nbsp; <b>X.stddev(</b>norm_type<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      vector of current standard deviations
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.cov()</b> &nbsp;and&nbsp; <b>X.cov(</b>norm_type<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      matrix of current covariances;
      valid if <i>calc_cov=true</i> during construction of <i>running_stat_vec</i>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.reset()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      reset all statistics and set the number of samples to zero
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>X.count()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      current number of samples
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<li>
The <i>calc_cov</i> argument is optional; by default <i>calc_cov=false</i>, indicating that the covariance matrix will not be calculated;
to enable the covariance matrix, use <i>calc_cov=true</i> during construction; for example: <i>running_stat_vec&lt;vec&gt;&nbsp;X(true);</i>
</li>
<br>
<li>
The <i>norm_type</i> argument is optional; by default <i>norm_type=0</i> is used
</li>
<br>
<li>
For the <i>.var()</i> and <i>.stddev()</i> functions, the default <i>norm_type=0</i> performs normalisation using <i>N-1</i>
(where <i>N</i> is the number of samples so far),
providing the best unbiased estimator;
using <i>norm_type=1</i> causes normalisation to be done using <i>N</i>, which provides the second moment around the mean
</li>
<br>
<li>
The return type of <i>.count()</i> depends on the underlying form of <i>vec_type</i>: it is either <i>float</i> or <i>double</i>
</li>
<br>
<li>
Examples:
<ul>
<pre>
running_stat_vec&lt;vec&gt; stats;

vec sample;

for(uword i=0; i&lt;10000; ++i)
  {
  sample = randu&lt;vec&gt;(5);
  stats(sample);
  }

cout &lt;&lt; "mean = " &lt;&lt; endl &lt;&lt; stats.mean() &lt;&lt; endl;
cout &lt;&lt; "var  = " &lt;&lt; endl &lt;&lt; stats.var()  &lt;&lt; endl;
cout &lt;&lt; "max  = " &lt;&lt; endl &lt;&lt; stats.max()  &lt;&lt; endl;

//
//

running_stat_vec&lt;rowvec&gt; more_stats(true);

for(uword i=0; i&lt;20; ++i)
  {
  sample = randu&lt;rowvec&gt;(3);
  
  sample(1) -= sample(0);
  sample(2) += sample(1);
  
  more_stats(sample);
  }

cout &lt;&lt; "covariance matrix = " &lt;&lt; endl;
cout &lt;&lt; more_stats.cov() &lt;&lt; endl;

rowvec sd = more_stats.stddev();

cout &lt;&lt; "correlations = " &lt;&lt; endl;
cout &lt;&lt; more_stats.cov() / (sd.t() * sd);
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#running_stat">running_stat</a> (running statistics of scalars)</li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#cov">cov()</a></li>
<li><a href="#cor">cor()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="kmeans"></a>
<b>kmeans(</b> means<b>,</b> data<b>,</b> k<b>,</b> seed_mode<b>,</b> n_iter<b>,</b> print_mode <b>)</b>
<ul>
<li>
Cluster given data into <i>k</i> disjoint sets
</li>
<br>
<li>
The <i>means</i> parameter is the output matrix for storing the resulting centroids of the sets, with each centroid stored as a column vector
</li>
<br>
<li>
The <i>data</i> parameter is the input data matrix, with each sample stored as a column vector
</li>
<br>
<li>
The <i>k</i> parameter indicates the number of centroids;
the number of samples in the <i>data</i> matrix should be much larger than <i>k</i>
</li>
<br>
<li>
The <i>seed_mode</i> parameter specifies how the initial centroids are seeded; it is one of:
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
  <tr><td><code>keep_existing</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>use the centroids specified in the <i>means</i> matrix as the starting point</td></tr>
  <tr><td><code>static_subset</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>use a subset of the data vectors (repeatable)</td></tr>
  <tr><td><code>random_subset</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>use a subset of the data vectors (random)</td></tr>
  <tr><td><code>static_spread</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>use a maximally spread subset of data vectors (repeatable)</td></tr>
  <tr><td><code>random_spread</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>use a maximally spread subset of data vectors (random start)</td></tr>
  </tbody>
</table>
<br>
<b>caveat:</b> seeding the initial centroids with <code>static_spread</code> and <code>random_spread</code>
can be much more time consuming than with <code>static_subset</code> and <code>random_subset</code>
</ul>
</li>
<br>
<li>
The <i>n_iter</i> parameter specifies the number of clustering iterations; this is data dependent, but about 10 is typically sufficient
</li>
<br>
<li>
The <i>print_mode</i> parameter is either <i>true</i> or <i>false</i>, indicating whether progress is printed during clustering
</li>
<br>
<li>
If the clustering fails, the <i>means</i> matrix is reset and a bool set to <i>false</i> is returned
</li>
<br>
<li>
The clustering will run faster on multi-core machines when OpenMP is enabled in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
</li>
<br>
<li>
Examples:
<ul>
<pre>
uword d = 5;       // dimensionality
uword N = 10000;   // number of vectors

mat data(d, N, fill::randu);

mat means;

bool status = kmeans(means, data, 2, random_subset, 10, true);

if(status == false)
  {
  cout &lt;&lt; "clustering failed" &lt;&lt; endl;
  }

means.print("means:");
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
<li><a href="http://en.wikipedia.org/wiki/K-means_clustering">k-means clustering in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/K-MeansClusteringAlgorithm.html">k-means clustering in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/OpenMP">OpenMP in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="gmm_diag"></a>
<a name="gmm_full"></a>
<b>gmm_diag</b>
<br><b>gmm_full</b>

<br>
<br>
<table border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td style="text-align: left; vertical-align: top; width: 55%;">

<ul>
<li>
Classes for multivariate data modelling and evaluation via <b>Gaussian Mixture Models</b> (GMMs)
</li>
<br>
<li>
The <i>gmm_diag</i> class is tailored for <b>diagonal covariance matrices</b> (ie. in each covariance matrix, all entries outside the main diagonal are assumed to be zero)
</li>
<br>
<li>
The <i>gmm_full</i> class is tailored for <b>full covariance matrices</b>
</li>
<br>
<li>
The <i>gmm_diag</i> class is typically much faster to train and use than the <i>gmm_full</i> class,
at the potential cost of some reduction in modelling accuracy
</li>
<br>
<li>
The <i>gmm_diag</i> and <i>gmm_full</i> classes include dedicated optimisation algorithms for learning (training) the model parameters from data:
<ul>
<li>k-means clustering, for quick initial estimates</li>
<li>Expectation-Maximisation (EM), for maximum-likelihood estimates</li>
</ul>
<br>
The optimisation algorithms are multi-threaded and can run much quicker on multi-core machines when OpenMP is enabled in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
</li>
<br>
<li>
The classes can also be used for probabilistic clustering and vector quantisation (VQ)
</li>
<br>
<li>
Data is modelled as:
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
  <tbody>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;"><i><sub>n_gaus-1</sub></i></td><td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>p<font size=+1>(</font>x<font size=+1>)</font></i></td><td style="vertical-align: top;">&nbsp;<font size=+1>=</font>&nbsp;</td><td style="vertical-align: top;"><i><font size=+1><b>&sum;</b></font></i></td>
      <td style="vertical-align: top;"><i>h<sub>g</sub></i>&nbsp;&nbsp;<font size=+1>N(</font><small>&nbsp;</small><i>x</i><small>&nbsp;</small>|<small>&nbsp;</small><i>m<sub>g</sub></i><small>&nbsp;</small>,&nbsp;<i>C<sub>g</sub></i><small>&nbsp;</small><font size=+1>)</font></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;">&nbsp;</td><td style="vertical-align: top;"><i><sup>g=0</sup></i></td><td style="vertical-align: top;">&nbsp;</td>
    </tr>
  </tbody>
</table>
where:
<ul>
<li><i>n_gaus</i> is the number of Gaussians; <i>n_gaus</i>&nbsp;&geq;1</li>
<li>N(<small>&nbsp;</small><i>x</i><small>&nbsp;</small>|<small>&nbsp;</small><i>m<sub>g</sub></i><small>&nbsp;</small>,&nbsp;<i>C<sub>g</sub></i><small>&nbsp;</small>) represents a Gaussian (normal) distribution</li>
<li>each Gaussian <i>g</i> has the following parameters:
<ul>
<li><i>h<sub>g</sub></i> is the heft (weight), with constraints <i>h<sub>g</sub></i>&nbsp;&ge;&nbsp;0 and &sum;<i>h<sub>g</sub></i> = 1</li>
<li><i>m<sub>g</sub></i> is the mean vector (centroid) with dimensionality <i>n_dims</i></li>
<li><i>C<sub>g</sub></i> is the covariance matrix (either diagonal or full)</li>
</ul>
</li>
</ul>
</li>
</ul>
</td>

<td>
&nbsp;
</td>
<td class="line" style="vertical-align: top;">
<br>
</td>
<td style="text-align: left; vertical-align: top; width: 40%;">

<ul>
<li>
Please cite the following paper if you use the <i>gmm_diag</i> or <i>gmm_full</i> classes in your research and/or software:
<br>
<br>Conrad Sanderson and Ryan Curtin.
<br><i><a href="armadillo_spcs_2017.pdf">An Open Source C++ Implementation of Multi-Threaded Gaussian Mixture Models, k-Means and Expectation Maximisation</a></i>.
<br><a class="latent" href="https://doi.org/10.1109/ICSPCS.2017.8270510">International Conference on Signal Processing and Communication Systems, 2017.</a>
</li>
</ul>

</td>
</tr>
</tbody>
</table>


<ul>
<li>
For an instance of <i>gmm_diag</i> or <i>gmm_full</i> named as <i>M</i>, the member functions and variables are:
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;">
      <b>M.log_p(</b>V<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the log-likelihood of vector <i>V</i> (of type <i>vec</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.log_p(</b>V, g<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the log-likelihood of vector <i>V</i> (of type <i>vec</i>), according to Gaussian with index&nbsp;<i>g</i>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.log_p(</b>X<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a row vector (of type <code>rowvec</code>) containing log-likelihoods of each column vector in matrix <i>X</i> (of type <i>mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.log_p(</b>X, g<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a row vector (of type <code>rowvec</code>) containing log-likelihoods of each column vector in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index&nbsp;<i>g</i>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.sum_log_p(</b>X<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the sum of log-likelihoods for all column vectors in matrix <i>X</i> (of type <i>mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.sum_log_p(</b>X, g<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the sum of log-likelihoods for all column vectors in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index&nbsp;<i>g</i>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.avg_log_p(</b>X<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the average log-likelihood of all column vectors in matrix <i>X</i> (of type <i>mat</i>)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.avg_log_p(</b>X, g<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a scalar representing the average log-likelihood of all column vectors in matrix <i>X</i> (of type <i>mat</i>), according to Gaussian with index&nbsp;<i>g</i>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.assign(</b>V,&nbsp;dist_mode<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return the index of the closest mean (or Gaussian) to vector <i>V</i> (of type <i>vec</i>);<br>
      parameter <i>dist_mode</i> is one of:
      <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
        <tbody>
        <tr><td style="vertical-align: top;"><code>eucl_dist</code></td><td>&nbsp;&nbsp;&nbsp;</td><td style="vertical-align: top;">Euclidean distance (takes only means into account)</td></tr>
        <tr><td style="vertical-align: top;"><code>prob_dist</code></td><td>&nbsp;&nbsp;&nbsp;</td><td style="vertical-align: top;">probabilistic "distance", defined as the inverse likelihood (takes into account means, covariances and hefts)</td></tr>
        </tbody>
      </table>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.assign(</b>X,&nbsp;dist_mode<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a row vector (of type <i>urowvec</i>) containing the indices of the closest means (or Gaussians) to each column vector in matrix <i>X</i> (of type <i>mat</i>);<br>
      parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.raw_hist(</b>X,&nbsp;dist_mode<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a row vector (of type <code>urowvec</code>) representing the raw histogram of counts;
      each entry is the number of counts corresponding to a Gaussian;
      each count is the number times the corresponding Gaussian was the closest to each column vector in matrix <i>X</i>;<br>
      parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.norm_hist(</b>X,&nbsp;dist_mode<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      similar to the <b>.raw_hist()</b> function above;
      return a row vector (of type <code>rowvec</code>) containing normalised counts;
      the vector sums to one;<br>
      parameter <i>dist_mode</i> is either <code>eucl_dist</code> or <code>prob_dist</code> (as per the <b>.assign()</b> function above)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.generate()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a column vector (of type <i>vec</i>) representing a random sample generated according to the model's parameters
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.generate(</b>N<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return a matrix (of type <i>mat</i>) containing <i>N</i> column vectors, with each vector representing a random sample generated according to the model's parameters
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.save(</b>filename<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      save the model to a file and return a <i>bool</i> indicating either success (<i>true</i>) or failure (<i>false</i>) 
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.load(</b>filename<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      load the model from a file and return a <i>bool</i> indicating either success (<i>true</i>) or failure (<i>false</i>) 
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.n_gaus()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return the number of means/Gaussians in the model
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.n_dims()</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      return the dimensionality of the means/Gaussians in the model
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.reset(</b>n_dims, n_gaus<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set the model to have dimensionality <i>n_dims</i>, with <i>n_gaus</i> number of Gaussians;<br>
      all the means are set to zero, all covariance matrix representations are equivalent to the identity matrix, and all the hefts (weights) are set to be uniform
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.hefts</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      read-only row vector (of type <i>rowvec</i>) containing the hefts (weights)
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.means</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      read-only matrix (of type <i>mat</i>) containing the means (centroids), stored as column vectors
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.dcovs</b>
      <br><i>[only&nbsp;in&nbsp;gmm_diag]</i>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      read-only matrix (of type <i>mat</i>) containing the representation of diagonal covariance matrices,
      with the set of diagonal covariances for each Gaussian stored as a column vector;
      applicable only to the <i>gmm_diag</i> class
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.fcovs</b>
      <br><i>[only&nbsp;in&nbsp;gmm_full]</i>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      read-only <a href="#Cube">cube</a> containing the full covariance matrices,
      with each covariance matrix stored as a slice within the cube;
      applicable only to the <i>gmm_full</i> class
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.set_hefts(</b>V<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set the hefts (weights) of the model to be as specified in row vector <i>V</i> (of type <i>rowvec</i>);
      the number of hefts must match the existing model
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.set_means(</b>X<b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set the means to be as specified in matrix <i>X</i> (of type <i>mat</i>);
      the number of means and their dimensionality must match the existing model
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.set_dcovs(</b>X<b>)</b>
      <br><i>[only&nbsp;in&nbsp;gmm_diag]</i>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set the diagonal covariances matrices to be as specified in matrix <i>X</i> (of type <i>mat</i>),
      with the set of diagonal covariances for each Gaussian stored as a column vector;
      the number of covariance matrices and their dimensionality must match the existing model;
      applicable only to the <i>gmm_diag</i> class
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.set_fcovs(</b>X<b>)</b>
      <br><i>[only&nbsp;in&nbsp;gmm_full]</i>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set the full covariances matrices to be as specified in cube <i>X</i>,
      with each covariance matrix stored as a slice within the cube;
      the number of covariance matrices and their dimensionality must match the existing model;
      applicable only to the <i>gmm_full</i> class
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <b>M.set_params(</b><small>means</small>,&nbsp;<small>covs</small>,&nbsp;<small>hefts</small><b>)</b>
      </td>
      <td style="vertical-align: top;">&nbsp;<br>
      </td>
      <td style="vertical-align: top;">
      set all the parameters at the same time;
      the type and layout of the parameters is as per the <b>.set_hefts()</b>, <b>.set_means()</b>, <b>.set_dcovs()</b> and <b>.set_fcovs()</b> functions above;
      the number of Gaussians and dimensionality can be different from the existing model
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
      <td style="vertical-align: top;">&nbsp;<br></td>
    </tr>
    <tr>
      <td style="vertical-align: top;" colspan=3>
      <b>M.learn(</b>data,&nbsp;n_gaus,&nbsp;dist_mode,&nbsp;seed_mode,&nbsp;km_iter,&nbsp;em_iter,&nbsp;var_floor,&nbsp;print_mode<b>)</b><br>
      learn the model parameters via multi-threaded k-means and/or EM algorithms;
      return a <code>bool</code> value, with <i>true</i> indicating success, and <i>false</i> indicating failure;
      the parameters have the following meanings:
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>data</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      matrix (of type <i>mat</i>) containing training samples; each sample is stored as a column vector
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>n_gaus</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      set the number of Gaussians to <i>n_gaus</i>;
      to help convergence, it is recommended that the given <i>data</i> matrix (above) contains at least 10 samples for each Gaussian
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>dist_mode</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      specifies the distance used during the seeding of initial means and k-means clustering:
      <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
        <tbody>
        <tr><td><code>eucl_dist</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>Euclidean distance</td></tr>
        <tr><td><code>maha_dist</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>Mahalanobis distance, which uses a global diagonal covariance matrix estimated from the training samples; this is recommended for probabilistic applications</td></tr>
        </tbody>
      </table>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>seed_mode</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      specifies how the initial means are seeded prior to running k-means and/or EM algorithms:
      <table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
        <tbody>
        <tr><td><code>keep_existing</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>keep the existing model (do not modify the means, covariances and hefts)</td></tr>
        <tr><td><code>static_subset</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>a subset of the training samples (repeatable)</td></tr>
        <tr><td><code>random_subset</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>a subset of the training samples (random)</td></tr>
        <tr><td><code>static_spread</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>a maximally spread subset of training samples (repeatable)</td></tr>
        <tr><td><code>random_spread</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>a maximally spread subset of training samples (random start)</td></tr>
        </tbody>
      </table>
      <br>
      <b>caveat:</b> seeding the initial means with <code>static_spread</code> and <code>random_spread</code>
      can be much more time consuming than with <code>static_subset</code> and <code>random_subset</code>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>km_iter</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      the number of iterations of the k-means algorithm;
      this is data dependent, but typically 10 iterations are sufficient
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>em_iter</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      the number of iterations of the EM algorithm;
      this is data dependent, but typically 5 to 10 iterations are sufficient
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>var_floor</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      the variance floor (smallest allowed value) for the diagonal covariances;
      setting this to a small non-zero value can help with convergence and/or better quality parameter estimates
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">&nbsp;</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><i>print_mode</i></td>
      <td style="vertical-align: top;">&nbsp;</td>
      <td style="vertical-align: top;">
      either <code>true</code> or <code>false</code>;
      enable or disable printing of progress during the k-means and EM algorithms
      </td>
    </tr>
  </tbody>
</table>
</ul>
</li>
<br>
<br>
<li>
Examples:
<ul>
<pre>
// create synthetic data with 2 Gaussians

uword d = 5;       // dimensionality
uword N = 10000;   // number of vectors

mat data(d, N, fill::zeros);

vec mean0 = linspace&lt;vec&gt;(1,d,d);
vec mean1 = mean0 + 2;

uword i = 0;

while(i &lt; N)
  {
  if(i &lt; N)  { data.col(i) = mean0 + randn&lt;vec&gt;(d); ++i; }
  if(i &lt; N)  { data.col(i) = mean0 + randn&lt;vec&gt;(d); ++i; }
  if(i &lt; N)  { data.col(i) = mean1 + randn&lt;vec&gt;(d); ++i; }
  }


// model the data as a diagonal GMM with 2 Gaussians

gmm_diag model;

bool status = model.learn(data, 2, maha_dist, random_subset, 10, 5, 1e-10, true);

if(status == false)
  {
  cout &lt;&lt; "learning failed" &lt;&lt; endl;
  }

model.means.print("means:");

double  scalar_likelihood = model.log_p( data.col(0)    );
rowvec     set_likelihood = model.log_p( data.cols(0,9) );

double overall_likelihood = model.avg_log_p(data);

uword   gaus_id  = model.assign( data.col(0),    eucl_dist );
urowvec gaus_ids = model.assign( data.cols(0,9), prob_dist );

urowvec hist1 = model.raw_hist (data, prob_dist);
 rowvec hist2 = model.norm_hist(data, eucl_dist);

model.save("my_model.gmm");
</pre>
</ul>
</li>
<br>
<li>See also:
<ul>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#mvnrnd">mvnrnd()</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
<li><a href="#kmeans">kmeans()</a></li>
<li><a href="https://en.wikipedia.org/wiki/Covariance_matrix">covariance matrix in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/CovarianceMatrix.html">covariance matrix in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Mahalanobis_distance">Mahalanobis distance in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Multivariate_normal_distribution">multivariate normal distribution in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/Mixture_model">mixture model in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/K-means_clustering">k-means clustering in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/K-MeansClusteringAlgorithm.html">k-means clustering in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Expectation-maximization_algorithm">Expectation-Maximisation algorithm in Wikipedia</a></li>
<li><a href="http://mathworld.wolfram.com/MaximumLikelihood.html">maximum likelihood in MathWorld</a></li>
<li><a href="http://en.wikipedia.org/wiki/Vector_quantization">vector quantisation in Wikipedia</a></li>
<li><a href="http://en.wikipedia.org/wiki/OpenMP">OpenMP in Wikipedia</a></li>
</ul>
</li>
<br>
</ul>



<div class="pagebreak"></div>
<hr class="greyline">
<hr class="greyline">
<br>
<br>
<font size=+1><b>Miscellaneous</b></font>
<br>
<br>



<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="constants"></a>
<b>constants (pi, inf, speed of light, ...)</b>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
<tbody>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::pi</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &pi;, the ratio of any circle's circumference to its diameter
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::inf</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &infin;, infinity
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::nan</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &ldquo;not a number&rdquo; (NaN); <b>caveat:</b> NaN is not equal to anything, even itself
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::e</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      base of the natural logarithm
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::sqrt2</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      square root of 2
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::sqrt2pi</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      square root of 2&pi;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::eps</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      machine epsilon: the difference between 1 and the value least greater than 1 that is representable  (type and machine dependent)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::log_min</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      log of minimum non-zero value (type and machine dependent)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::log_max</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      log of maximum value  (type and machine dependent)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::euler</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Euler's constant, aka Euler-Mascheroni constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::gratio</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      golden ratio
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::m_u</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      atomic mass constant (in kg)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::N_A</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Avogadro constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::k</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Boltzmann constant (in joules per kelvin)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::k_evk</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Boltzmann constant (in eV/K)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::a_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Bohr radius (in meters)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::mu_B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Bohr magneton
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::Z_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      characteristic impedance of vacuum (in ohms)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::G_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      conductance quantum (in siemens)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::k_e</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Coulomb's constant (in meters per farad)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::eps_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      electric constant (in farads per meter)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::m_e</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      electron mass (in kg)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::eV</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      electron volt (in joules)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::ec</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      elementary charge (in coulombs)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::F</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Faraday constant (in coulombs)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::alpha</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      fine-structure constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::alpha_inv</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      inverse fine-structure constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::K_J</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Josephson constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::mu_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      magnetic constant (in henries per meter)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::phi_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      magnetic flux quantum (in webers)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::R</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      molar gas constant (in joules per mole kelvin)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::G</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Newtonian constant of gravitation (in newton square meters per kilogram squared)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::h</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Planck constant (in joule seconds)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::h_bar</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Planck constant over 2 pi, aka reduced Planck constant (in joule seconds)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::m_p</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      proton mass (in kg)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::R_inf</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Rydberg constant (in reciprocal meters)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::c_0</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      speed of light in vacuum (in meters per second)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
    <td style="vertical-align: top;">&nbsp;</td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::sigma</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Stefan-Boltzmann constant
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::R_k</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      von Klitzing constant (in ohms)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>datum::b</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Wien wavelength displacement law constant
    </td>
  </tr>
</tbody>
</table>
<br>
<li>
The constants are stored in the <i>Datum&lt;type&gt;</i> class,
where <i>type</i> is either <i>float</i> or <i>double</i>;
<br>
for convenience,
<i>Datum&lt;double&gt;</i> is typedefed as <i>datum</i>,
and
<i>Datum&lt;float&gt;</i> is typedefed as <i>fdatum</i>
</li>
<br>
<li>
<b>Caveat:</b>
<code>datum::nan</code> is not equal to anything, even itself;
to check whether a scalar <i>x</i> is finite,
use <a href="https://en.cppreference.com/w/cpp/numeric/math/isfinite">std::isfinite</a>(<i>x</i>)
</li>
<br>
<li>
The physical constants were mainly taken from
<a href="http://physics.nist.gov/cuu/Constants">NIST 2018 CODATA values</a>,
and some from
<a href="http://www.wolframalpha.com">WolframAlpha</a> (as of 2009-06-23)
</li>
<br>
<li>
Examples:
<ul>
<pre>
cout &lt;&lt; "2.0 * pi = " &lt;&lt; 2.0 * datum::pi &lt;&lt; endl;

cout &lt;&lt; "speed of light = " &lt;&lt; datum::c_0 &lt;&lt; endl;

cout &lt;&lt; "log_max for floats = ";
cout &lt;&lt; fdatum::log_max &lt;&lt; endl;

cout &lt;&lt; "log_max for doubles = ";
cout &lt;&lt; datum::log_max &lt;&lt; endl;
</pre>
</ul>
</li>
<li>
See also:
<ul>
<li><a href="#is_finite">.is_finite()</a></li>
<li><a href="#fill">.fill()</a></li>
<li><a href="http://en.wikipedia.org/wiki/NaN">NaN</a> in Wikipedia</li>
<li><a href="http://en.wikipedia.org/wiki/Physical_constant">physical constant</a> in Wikipedia</li>
<li><a href="http://cplusplus.com/reference/std/limits/numeric_limits/">std::numeric_limits</a></li>
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="wall_clock"></a>
<b>wall_clock</b>
<ul>
<li>
Simple wall clock timer class for measuring the number of elapsed seconds
</li>
<br>
<li>
Examples:
<ul>
<pre>
wall_clock timer;

mat A(100, 100, fill::randu);
mat B(100, 100, fill::randu);
mat C;

timer.tic();

for(uword i=0; i&lt;100000; ++i)
  {
  C = A + B + A + B;
  }

double n = timer.toc();

cout &lt;&lt; "number of seconds: " &lt;&lt; n &lt;&lt; endl;
</pre>
</ul>
</li>
</ul>
<br>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="logging"></a>
<b>logging of warnings and errors</b>
<br>
<br><b>set_cerr_stream( user_stream )</b>
<br><b>set_cout_stream( user_stream )</b>
<br>
<br><b>std::ostream&amp; x = get_cerr_stream()</b>
<br><b>std::ostream&amp; x = get_cout_stream()</b>
<br>
<ul>
<li>
In Armadillo 8.x and later versions, warnings and errors are printed by default to the <i>std::cerr</i> stream;
in Armadillo 7.x and earlier, the <i>std::cout</i> stream is used
<ul>
<li>the printing can be disabled by placing <i>#define <a href="#config_hpp">ARMA_DONT_PRINT_ERRORS</a></i> before <i>#include&nbsp;&lt;armadillo&gt;</i></li>
<li>detailed information about errors is always reported via the base <i>std::exception</i> class</li>
</ul>
</li>
<br>
<li><b>set_cerr_stream()</b>:
<ul>
<li>change the stream for printing warnings and errors involving out of bounds accesses, failed decompositions and out of memory conditions</li>
<li>the stream can also be changed via the ARMA_CERR_STREAM define; see <a href="#config_hpp">config.hpp</a></li>
</ul>
</li>
<br>
<li><b>set_cout_stream()</b>:
<ul>
<li>change the default stream for printing matrices and cubes with <a href="#print">.print()</a> and <a href="#raw_print">.raw_print()</a></li>
<li>the stream can also be changed via the ARMA_COUT_STREAM define; see <a href="#config_hpp">config.hpp</a></li>
</ul>
</li>
<br>
<li><b>get_cerr_stream()</b>:
<ul>
<li>get a reference to the stream for printing warnings and errors</li>
</ul>
<br>
<li><b>get_cout_stream()</b>:
<ul>
<li>get a reference to the stream for printing matrices and cubes</li>
</ul>
<br>
<li>
Examples:
<ul>
<pre>
// print error messages to a log file
ofstream f("my_log.txt");
set_cerr_stream(f);

// trying to invert a singular matrix
// will print an error message and throw an exception
mat X(5, 5, fill::zeros);
mat Y = inv(X);

// disable printing of error messages
std::ostream nullstream(0);
set_cerr_stream(nullstream);
</pre>
</ul>
</li>
<br>
<li>
See also:
<ul>
<li><a href="#config_hpp">config.hpp</a></li>
<li><a href="#print">.print()</a></li>
<li><a href="http://cplusplus.com/reference/iostream/cout/">std::cout</a></li>
<li><a href="http://cplusplus.com/reference/iostream/ostream/">std::ostream</a></li>
<li><a href="http://cplusplus.com/reference/exception/exception/">std::exception</a></li>
<li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li>
</ul>
</li>
<br>
</ul>

<!--
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="log_add"></a>
<b>log_add(log_a, log_b)</b>
<ul>
<li>
Safe replacement for log(exp(log_a) + exp(log_b))
</li>
<br>
<li>
Usage:
<ul>
<li>
<i>scalar_type</i> log_c = log_add(log_a, log_b)
</li>
<li>
<i>scalar_type</i> is either <i>float</i> or <i>double</i>
</li>
<li>
log_a, log_b and log_c must have the same type
</li>
</ul>
</li>
</ul>
<br>
-->

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="uword"></a>
<b>uword</b>, <b>sword</b>
<ul>
<li><i>uword</i> is a typedef for an unsigned integer type; it is used for matrix <a href="#element_access">indices</a> as well as all internal counters and loops</li>
<br>
<li><i>sword</i> is a typedef for a signed integer type</li>
<br>
<li>The minimum width of both <i>uword</i> and <i>sword</i> is either 32 or 64 bits:
<ul>
<li>the default width is 32 bits on 32-bit platforms</li>
<li>the default width is 64 bits on 64-bit platforms</li>
<li>the default width is 32 bits when using Armadillo in the R environment (via RcppArmadillo) on either 32-bit or 64-bit platforms</li>
</ul>
</li>
<br>
<li>The width can also be forcefully set to 64 bits by enabling <a href="#config_hpp_arma_64bit_word"><i>ARMA_64BIT_WORD</i></a> via editing <i>include/armadillo_bits/config.hpp</i></li>
<br>
<li>See also:
<ul>
<li><a href="http://cplusplus.com/doc/tutorial/variables/">C++ variable types</a></li>
<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li>
<li><a href="#Mat">imat &amp; umat</a> matrix types
<li><a href="#Col">ivec &amp; uvec</a> vector types
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="cx_double"></a>
<b>cx_double</b>, <b>cx_float</b> 
<ul>
<li>
<i>cx_double</i> is a shorthand / typedef for <i>std::complex&lt;double&gt;</i>
</li>
<br>
<li>
<i>cx_float</i> is a shorthand / typedef for <i>std::complex&lt;float&gt;</i>
</li>
<br>
<li>
Example:
<ul>
<pre>
cx_mat X(5, 5, fill::randu);

X(1,2) = cx_double(2.0, 3.0);
</pre>
</ul>
</li>
<li>See also:
<ul>
<li><a href="http://cplusplus.com/reference/std/complex/">complex numbers in the standard C++ library</a></li>
<li><a href="http://www.cplusplus.com/doc/tutorial/other_data_types/">explanation of <i>typedef</i></a></li>
<li><a href="#Mat">cx_mat</a> matrix type
<li><a href="#Col">cx_vec</a> vector type
</ul>
</li>
<br>
</ul>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="syntax"></a>
<b>Examples of Matlab/Octave syntax and conceptually corresponding Armadillo syntax</b>
<br>
<br>
<ul>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
<tbody>
  <tr>
    <td style="vertical-align: top;">
      <b>Matlab/Octave</b>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <b>Armadillo</b>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <b>Notes</b>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(1, 1)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A(0, 0)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      indexing in Armadillo starts at 0
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(k, k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A(k-1, k-1)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>size(A,1)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#attributes">.n_rows</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      read only
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>size(A,2)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#attributes">.n_cols</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>size(Q,3)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>Q<a href="#attributes">.n_slices</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Q is a <a href="#Cube">cube</a> (3D array)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>numel(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#attributes">.n_elem</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(:, k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#submat">.col</a>(k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
this is a conceptual example only; 
exact conversion from Matlab/Octave to Armadillo syntax
will require taking into account that indexing starts at 0
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(k, :)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#submat">.row</a>(k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(:, p:q)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#submat">.cols</a>(p, q)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(p:q, :)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#submat">.rows</a>(p, q)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A(p:q, r:s)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A(&nbsp;<a href="#submat">span</a>(p,q),&nbsp;<a href="#submat">span</a>(r,s)&nbsp;)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      A(&nbsp;span(first_row,&nbsp;last_row), span(first_col,&nbsp;last_col)&nbsp;)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>Q(:, :, k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>Q<a href="#subcube">.slice</a>(k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Q is a <a href="#Cube">cube</a> (3D array)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>Q(:, :, t:u)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>Q<a href="#subcube">.slices</a>(t, u)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>Q(p:q, r:s, t:u)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <font size=-1>
      <code>Q(&nbsp;<a href="#subcube">span</a>(p,q),&nbsp;<a href="#subcube">span</a>(r,s),&nbsp;<a href="#subcube">span</a>(t,u)&nbsp;)</code>
      </font>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A'</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#t_st_members">.t()</a> or <a href="#trans">trans</a>(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      matrix transpose / Hermitian transpose
      <br>
      (for complex matrices, the conjugate of each element is taken)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A&nbsp;=&nbsp;zeros(size(A))</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#zeros_member">.zeros()</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A&nbsp;=&nbsp;ones(size(A))</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A.<a href="#ones_member">ones()</a></code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A = zeros(k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A = <a href="#zeros_standalone">zeros</a>&lt;mat&gt;(k,k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A = ones(k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A = <a href="#ones_standalone">ones</a>&lt;mat&gt;(k,k)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>C = complex(A,B)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>cx_mat C = <a href="#Mat">cx_mat</a>(A,B)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A .* B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A % B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <a href="#operators">element-wise multiplication</a>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A ./ B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A / B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <a href="#operators">element-wise division</a>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A \ B</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code><a href="#solve">solve</a>(A,B)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      conceptually similar to <a href="#inv">inv</a>(A)*B, but more efficient
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A = A + 1;</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A++</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A = A - 1;</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A--</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A = [ 1 2; 3 4; ]</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
    <code>
    A&nbsp;=&nbsp;{ { 1, 2 },<br>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ 3, 4 } };
    </code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <a href="#element_initialisation">element initialisation</a>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>X = A(:)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>X = <a href="#vectorise">vectorise</a>(A)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>X = [&nbsp;A&nbsp;&nbsp;B&nbsp;]</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>X = <a href="#join">join_horiz</a>(A,B)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>X = [&nbsp;A;&nbsp;B&nbsp;]</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>X = <a href="#join">join_vert</a>(A,B)</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>cout <font size=-1>&lt;&lt;</font> A <font size=-1>&lt;&lt;</font> endl;</code>
      <br><font size=-1>or</font>
      <br><code>A<a href="#print">.print</a>("A =");</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>save&nbsp;&#8209;ascii&nbsp;'A.txt'&nbsp;A</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#save_load_mat">.save</a>("A.txt",&nbsp;raw_ascii);</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      Matlab/Octave matrices saved as ascii are readable by Armadillo (and vice-versa)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>load&nbsp;&#8209;ascii&nbsp;'A.txt'</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>A<a href="#save_load_mat">.load</a>("A.txt",&nbsp;raw_ascii);</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      <code>A&nbsp;=&nbsp;randn(2,3);
      <br>B&nbsp;=&nbsp;randn(4,5);
      <br>F&nbsp;=&nbsp;{&nbsp;A;&nbsp;B&nbsp;}</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      <code>mat&nbsp;A&nbsp;=&nbsp;randn(2,3);
      <br>mat&nbsp;B&nbsp;=&nbsp;randn(4,5);
      <br><a href="#field">field</a>&lt;mat&gt;&nbsp;F(2,1);
      <br>F(0,0)&nbsp;=&nbsp;A;
      <br>F(1,0)&nbsp;=&nbsp;B;</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: center;">
      <a href="#field">fields</a> store arbitrary objects, such as matrices
    </td>
  </tr>
</tbody>
</table>
</ul>
<br>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="example_prog"></a>
<b>example program</b>
<br>
<ul>
<pre>
#include &lt;iostream&gt;
#include &lt;armadillo&gt;

using namespace std;
using namespace arma;

int main()
  {
  mat A(4, 5, fill::randu);
  mat B(4, 5, fill::randu);
  
  cout &lt;&lt; A*B.t() &lt;&lt; endl;
  
  return 0;
  }
</pre>
<li>
If you save the above program as <i>example.cpp</i>,
under Linux and macOS it can be compiled using:
<br>
<ul><code>g++ example.cpp -o example -std=c++11 -O2 -larmadillo</code></ul>
</li>
<br>
<li>
Armadillo extensively uses template meta-programming,
so it's recommended to enable optimisation when compiling programs (eg. use the -O2 or -O3 options for GCC or clang)
</li>
<br>
<li>See the <a href="http://arma.sourceforge.net/faq.html">Questions</a> page for more info on compiling and linking</li>
<br>
<li>See also the example program that comes with the Armadillo archive</li>
</ul>
<br>

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="config_hpp"></a>
<b>config.hpp</b>
<br>
<ul>
<li>
Armadillo can be configured via editing the file <i>include/armadillo_bits/config.hpp</i>.
Specific functionality can be enabled or disabled by uncommenting or commenting out a particular <i>#define</i>, listed below.
<br>
<br>
<table style="text-align: left;" border="0" cellpadding="2" cellspacing="2">
<tbody>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_WRAPPER</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable going through the run-time Armadillo wrapper library (<i>libarmadillo.so</i>) when calling LAPACK, BLAS, ARPACK, SuperLU and HDF5 functions.
You will need to directly link with BLAS, LAPACK, etc (eg. <code><i>-lblas -llapack</i></code>)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_LAPACK</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable use of LAPACK, or a high-speed replacement for LAPACK (eg. OpenBLAS, Intel MKL, or the Accelerate framework).
Armadillo requires LAPACK for functions such as <a href="#svd">svd()</a>, <a href="#inv">inv()</a>, <a href="#eig_sym">eig_sym()</a>, <a href="#solve">solve()</a>, etc.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_LAPACK</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of LAPACK; overrides <i>ARMA_USE_LAPACK</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_BLAS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, or the Accelerate framework).
BLAS is used for <a href="#operators">matrix multiplication</a>.
Without BLAS, Armadillo will use a built-in matrix multiplication routine, which might be slower for large matrices.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_BLAS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of BLAS; overrides <i>ARMA_USE_BLAS</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_NEWARP</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable use of NEWARP (built-in alternative to ARPACK).
This is used for the eigen decomposition of real (non-complex) sparse matrices, ie. <a href="#eigs_gen">eigs_gen()</a>, <a href="#eigs_sym">eigs_sym()</a> and <a href="#svds">svds().</a>
Requires ARMA_USE_LAPACK to be enabled.
If use of both NEWARP and ARPACK is enabled, NEWARP will be preferred.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_NEWARP</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of NEWARP (built-in alternative to ARPACK); overrides <i>ARMA_USE_NEWARP</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_ARPACK</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable use of ARPACK, or a high-speed replacement for ARPACK.
Armadillo requires ARPACK for the eigen decomposition of complex sparse matrices, ie. <a href="#eigs_gen">eigs_gen()</a>, <a href="#eigs_sym">eigs_sym()</a> and <a href="#svds">svds()</a>.
If use of NEWARP is disabled, ARPACK will also be used for the eigen decomposition of real sparse matrices.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_ARPACK</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of ARPACK; overrides <i>ARMA_USE_ARPACK</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_SUPERLU</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable use of SuperLU, which is used by <a href="#spsolve">spsolve()</a> for finding the solutions of sparse systems;
you will need to link with the superlu library, for example <code><i>-lsuperlu</i></code>
<br><b>Caveat:</b> Armadillo&nbsp;7.x and later versions require SuperLU&nbsp;5.2
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_SUPERLU</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of SuperLU; overrides <i>ARMA_USE_SUPERLU</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_HDF5</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Enable the ability to <a href="#save_load_mat">save and load</a> matrices stored in the HDF5 format;
the <i>hdf5.h</i> header file must be available on your system and you will need to link with the hdf5 library (eg. <code><i>-lhdf5</i></code>)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_HDF5</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable the use of the HDF5 library; overrides <i>ARMA_USE_HDF5</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_STD_MUTEX</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of <i>std::mutex</i>; applicable if your compiler and/or environment doesn't support <i>std::mutex</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_OPTIMISE_BAND</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable automatically optimised handling of band matrices by <a href="#solve">solve()</a> and <a href="#chol">chol()</a>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_OPTIMISE_SYMPD</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable automatically optimised handling of symmetric/hermitian positive definite matrices by
<a href="#solve">solve()</a>,
<a href="#inv">inv()</a>,
<a href="#expmat">expmat()</a>,
<a href="#logmat">logmat()</a>,
<a href="#sqrtmat">sqrtmat()</a>,
<a href="#powmat">powmat()</a>,
<a href="#rcond">rcond()</a>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_OPENMP</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use OpenMP for parallelisation of computationally expensive element-wise operations
(such as <a href="#misc_fns">exp()</a>, <a href="#misc_fns">log()</a>, <a href="#trig_fns">cos()</a>, etc).
Automatically enabled when using a compiler which has OpenMP 3.1+ active (eg. the <code>-fopenmp</code> option for gcc and clang).
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_OPENMP</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of OpenMP for parallelisation of element-wise operations; overrides <i>ARMA_USE_OPENMP</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_OPENMP_THRESHOLD</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
The minimum number of elements in a matrix to enable OpenMP based parallelisation of computationally expensive element-wise functions; default value is 240
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_OPENMP_THREADS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
The maximum number of threads for OpenMP based parallelisation of computationally expensive element-wise functions; default value is 10
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_BLAS_CAPITALS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use capitalised (uppercase) BLAS and LAPACK function names (eg. DGEMM vs dgemm)
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_BLAS_UNDERSCORE</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Append an underscore to BLAS and LAPACK function names (eg. dgemm_ vs dgemm). Enabled by default.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_BLAS_LONG</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use "long" instead of "int" when calling BLAS and LAPACK functions
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_BLAS_LONG_LONG</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use "long&nbsp;long" instead of "int" when calling BLAS and LAPACK functions
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_FORTRAN_HIDDEN_ARGS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use so-called "hidden arguments" when calling BLAS and LAPACK functions.  Enabled by default.
See Fortran <a href="https://gcc.gnu.org/onlinedocs/gfortran/Argument-passing-conventions.html">argument passing conventions</a> for more details.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable use of so-called "hidden arguments" when calling BLAS and LAPACK functions.
May be necessary when using Armadillo in conjunction with broken MKL headers (eg. if you have <code>#include "mkl_lapack.h"</code> in your code).
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_TBB_ALLOC</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use Intel TBB <i>scalable_malloc()</i> and <i>scalable_free()</i> instead of standard <i>malloc()</i> and <i>free()</i> for managing matrix memory
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_MKL_ALLOC</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use Intel MKL <i>mkl_malloc()</i> and <i>mkl_free()</i> instead of standard <i>malloc()</i> and <i>free()</i> for managing matrix memory
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_USE_MKL_TYPES</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use Intel MKL types for complex numbers.
You will need to include appropriate MKL headers before the Armadillo header.
You may also need to enable one or more of the following options:
<code>ARMA_BLAS_LONG</code>, <code>ARMA_BLAS_LONG_LONG</code>, <code>ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<a name="config_hpp_arma_64bit_word"></a>
<code>ARMA_64BIT_WORD</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Use 64 bit integers. Automatically enabled when using a 64-bit platform, except when using Armadillo in the R environment (via RcppArmadillo).
Useful if you require matrices/vectors capable of holding more than 4 billion elements.
<!-- Your machine and compiler must have support for 64 bit integers (eg. via "long" or "long&nbsp;long"). -->
This can also be enabled by adding <i>#define&nbsp;ARMA_64BIT_WORD</i> before each instance of <i>#include&nbsp;&lt;armadillo&gt;</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<a name="config_hpp_arma_no_debug"></a>
<code>ARMA_NO_DEBUG</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Disable all run-time checks, such as <a href="#element_access">bounds checking</a>.
This will result in faster code, but you first need to make sure that your code runs correctly!
We strongly recommend to have the run-time checks enabled during development,
as this greatly aids in finding mistakes in your code, and hence speeds up development.
We recommend that run-time checks be disabled <b>only</b> for the shipped version of your program
(ie. final release build).
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_EXTRA_DEBUG</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Print out the trace of internal functions used for evaluating expressions.
Not recommended for normal use.
This is mainly useful for debugging the library.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_MAT_PREALLOC</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
The number of pre-allocated elements used by matrices and vectors.
Must be always enabled and set to an integer that is at least&nbsp;1.
By default set to 16.
If you mainly use lots of very small vectors (eg.&nbsp;&le;&nbsp;4&nbsp;elements), change the number to the size of your vectors.
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_COUT_STREAM</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
The default stream used for printing matrices and cubes by <a href="#print">.print()</a>.
Must be always enabled.
By default defined to <i>std::cout</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_CERR_STREAM</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
The default stream used for printing <a href="#logging">error messages and warnings</a>.
Must be always enabled.
By default defined to <i>std::cerr</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_PRINT_ERRORS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Print errors and warnings encountered during program execution
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
<code>ARMA_DONT_PRINT_ERRORS</code>
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
Do not print errors or warnings; overrides <i>ARMA_PRINT_ERRORS</i>
    </td>
  </tr>
  <tr>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
    <td style="vertical-align: top;">
      &nbsp;
    </td>
  </tr>
</tbody>
</table>
</li>

<br>
<li>
See also:
<ul>
<li><a href="#logging">logging of warnings and errors</a></li>
<li><a href="#element_access">element access</a></li>
<li><a href="#element_initialisation">element initialisation</a></li>
<li><a href="#uword">uword/sword</a></li>
</ul>
</li>
<br>
</ul>

<!--
<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="catching_exceptions"></a>
<br>
<b>how to catch std::runtime_error exceptions</b>
<br>
<br>
<ul>
<li>
If a function such as <a href="#inv">inv()</a> fails to find a solution,
an error message is printed and a <i>std::runtime_error</i> exception is thrown.
If the exception is not caught, the program typically terminates.
Below is an example of how to catch exceptions:
<ul>
<pre>
#include &lt;iostream&gt;
#include &lt;armadillo&gt;

using namespace std;
using namespace arma;

int main(int argc, char** argv)
  {
  // create a non-invertible matrix
  mat A(5, 5, fill::zeros);
  
  mat B;
  
  try
    {
    B = inv(A);
    }
  catch (std::runtime_error&amp; x)
    {
    cout &lt;&lt; "caught an exception" &lt;&lt; endl;
    }
  
  return 0;
  }
</pre>
</ul>
<li>
See also:
<ul>
<li><a href="#logging">logging of warnings and errors</a></li>
<li><a href="http://cplusplus.com/doc/tutorial/exceptions/">tutorial on exceptions</a></li>
<li><a href="http://cplusplus.com/reference/std/stdexcept/runtime_error/">std::runtime_error</a></li>
</ul>
</li>
<br>
</ul>
<br>
-->

<div class="pagebreak"></div><div class="noprint"><hr class="greyline"><br></div>
<a name="api_additions"></a>
<a name="api_changes"></a>
<b>History of API Additions, Changes and Deprecations</b>
<br>
<ul>
<li>API Stability and Versioning:
<br>
<br>
<ul>
<li>
Each release of Armadillo has its public API (functions, classes, constants) described in the accompanying API documentation specific to that release.
</li>
<br>
<li>
Each release of Armadillo has its full version specified as <i>A.B.C</i>, where <i>A</i> is a major version number, <i>B</i> is a minor version number, and <i>C</i> is a patch level (indicating bug fixes).
</li>
<br>
<li>
Within a major version (eg. 7), each minor version has a public API that strongly strives to be <b>backwards compatible</b> (at the source level) with the public API of preceding minor versions.
For example, user code written for version 7.100 should work with version 7.200, 7.300, 7.400, etc.
However, as later minor versions may have more features (API extensions) than preceding minor versions, user code specifically written for version 7.400 may not work with 7.300.
</li>
<br>
<li>
An increase in the patch level, while the major and minor versions are retained, indicates modifications to the code and/or documentation which aim to fix bugs without altering the public API.
</li>
<br>
<li>
We don't like changes to existing public API and strongly prefer not to break any user software.
However, to allow evolution, we reserve the right to alter the public API in future major versions of Armadillo while remaining backwards compatible in as many cases as possible
(eg. major version 8 may have slightly different public API than major version 7).
</li>
<br>
<li>
<b>Caveat:</b> any function, class, constant or other code <u>not</u> explicitly described in the public API documentation is considered as part of the underlying internal implementation details,
and may be removed or changed without notice.
(In other words, don't use internal functionality).
</li>
</ul>
</li>

<!--
<br>
<li>
<a name="deprecated"></a>
List of deprecated functionality; this functionality will be <b>removed</b> in version A.B:
<ul>
<li>
...
</li>
</ul>
</li>
-->

<br>
<br>
<li>
List of additions and changes for each version:
<br>
<br>
<ul>



<a name="version_101"></a>
<li>Version 10.1:
<ul>
<li>C++11 is now the minimum required C++ standard</li>
<li>faster handling of compound expressions by <a href="#trimat">trimatu()</a> and <a href="#trimat">trimatl()</a></li>
<li>faster sparse matrix addition, subtraction and element-wise multiplication</li>
<li>expanded sparse <a href="#submat">submatrix views</a> to handle the non-contiguous form of <i>X.cols(vector_of_column_indices)</i></li>
<li>expanded <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> with optional fine-grained parameters</li>
</ul>
</li>
<br>
<a name="version_9900"></a>
<li>Version 9.900:
<ul>
<li>faster <a href="#solve">solve()</a> for under/over-determined systems</li>
<li>faster <a href="#eig_gen">eig_gen()</a> and <a href="#eig_pair">eig_pair()</a> for large matrices</li>
<li>faster handling of matrix multiplication expressions by <a href="#diagvec">diagvec()</a> and <a href="#diagmat">diagmat()</a></li>
<li>faster handling of relational expressions by <a href="#accu">accu()</a></li>
<li>faster handling of sympd matrices by <a href="#expmat">expmat()</a>, <a href="#logmat">logmat()</a>, <a href="#sqrtmat">sqrtmat()</a></li>
<li>faster access to columns in sparse submatrix views</li>
<li>added <a href="#quantile">quantile()</a></li>
<li>added <a href="#powmat">powmat()</a></li>
<li>added <a href="#trimat_ind">trimatu_ind()</a> and <a href="#trimat_ind">trimatl_ind()</a></li>
<li>added <a href="#log_normpdf">log_normpdf()</a></li>
<li>added <a href="#is_zero">.is_zero()</a></li>
<li>added <code>ARMA_DONT_USE_CXX11_MUTEX</code> <a href="#config_hpp">configuration option</a> to disable use of <i>std::mutex</i></li>
<li>expanded <a href="#eig_gen">eig_gen()</a> and <a href="#eig_pair">eig_pair()</a> to optionally provide left and right eigenvectors</li>
<li>expanded <a href="#qr">qr()</a> to optionally use pivoted decomposition</li>
<li>expanded <a href="#save_load_mat">.save()</a> and <a href="#save_load_mat">.load()</a> to handle CSV files with headers via <i>csv_name(filename,header)</i> specification</li>
<li>more consistent detection of sparse vector expressions</li>
<li>updated <a href="#constants">physical constants</a> to NIST 2018 CODATA values</li>
<li>workaround for <a href="#save_load_mat">save/load</a> issues with HDF5 v1.12</li>
</ul>
</li>
<br>
<a name="version_9800"></a>
<li>Version 9.800:
<ul>
<li>faster <a href="#solve">solve()</a> in default operation; iterative refinement is no longer applied by default; use <code>solve_opts::refine</code> to explicitly enable refinement</li>
<li>faster <a href="#expmat">expmat()</a></li>
<li>faster handling of triangular matrices by <a href="#rcond">rcond()</a></li>
<li>added <a href="#compat_container_fns">.front()</a> and <a href="#compat_container_fns">.back()</a>
<li>added <a href="#is_trimat">.is_trimatu()</a> and <a href="#is_trimat">.is_trimatl()</a></li>
<li>added <a href="#is_diagmat">.is_diagmat()</a></li>
</ul>
</li>
<br>
<a name="version_9700"></a>
<li>Version 9.700:
<ul>
<li>faster handling of cubes by <a href="#vectorise">vectorise()</a></li>
<li>faster handling of sparse matrices by <a href="#nonzeros">nonzeros()</a></li>
<li>faster row-wise <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a></li>
<li>expanded <a href="#join">join_rows()</a> and <a href="#join">join_cols()</a> to handle joining up to 4 matrices</li>
<li>expanded <a href="#save_load_mat">.save()</a> and <a href="#save_load_mat">.load()</a> to allow storing sparse matrices in CSV format</li>
<li>added <a href="#randperm">randperm()</a> to generate a vector with random permutation of a sequence of integers</li>
</ul>
</li>
<br>
<a name="version_9600"></a>
<li>Version 9.600:
<ul>
<li>faster handling of sparse <a href="#submat">submatrices</a></li>
<li>faster handling of sparse <a href="#diag">diagonal views</a></li>
<li>faster handling of sparse matrices by <a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li>
<li>faster handling of sparse matrices by <a href="#join">join_cols()</a></li>
<li>expanded <a href="#clamp">clamp()</a> to handle sparse matrices</li>
<li>added <a href="#clean">.clean()</a> to replace elements below a threshold with zeros</li>
</ul>
</li>
<br>
<a name="version_9500"></a>
<li>Version 9.500:
<ul>
<li>expanded <a href="#solve">solve()</a> with <code>solve_opts::likely_sympd</code> to indicate that the given matrix is likely positive definite</li>
<li>more robust automatic detection of positive definite matrices by <a href="#solve">solve()</a> and <a href="#inv">inv()</a></li>
<li>faster handling of sparse submatrices</li>
<li>expanded <a href="#eigs_sym">eigs_sym()</a> to print a warning if the given matrix is not symmetric</li>
<li>
extended LAPACK function prototypes to follow Fortran <a href="https://gcc.gnu.org/onlinedocs/gfortran/Argument-passing-conventions.html">passing conventions</a> for so-called "hidden arguments",
in order to address <a href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=90329">GCC Bug 90329</a>;
<br>
to use previous LAPACK function prototypes without the "hidden arguments",
<code>#define ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS</code> before <code>#include &lt;armadillo&gt;</code>
</li>
</ul>
</li>
<br>
<a name="version_9400"></a>
<li>Version 9.400:
<ul>
<li>faster <a href="#cov">cov()</a> and <a href="#cor">cor()</a></li>
<li>added <a href="#as_col_row">.as_col()</a> and <a href="#as_col_row">.as_row()</a></li>
<li>expanded <a href="#shed">.shed_rows()</a> / <a href="#shed">.shed_cols()</a> / <a href="#shed">.shed_slices()</a> to remove rows/columns/slices specified in a vector</li>
<li>expanded <a href="#vectorise">vectorise()</a> to handle sparse matrices</li>
<li>expanded element-wise versions of <a href="#min_and_max">max()</a> and <a href="#min_and_max">min()</a> to handle sparse matrices</li>
<li>optimised handling of sparse matrix expressions: sparse&nbsp;%&nbsp;(sparse&nbsp;+-&nbsp;scalar) and sparse&nbsp;/&nbsp;(sparse&nbsp;+-&nbsp;scalar)</li>
<li>
expanded
<a href="#eig_sym">eig_sym()</a>,
<a href="#chol">chol()</a>,
<a href="#expmat_sym">expmat_sym()</a>,
<a href="#logmat_sympd">logmat_sympd()</a>,
<a href="#sqrtmat_sympd">sqrtmat_sympd()</a>,
<a href="#inv_sympd">inv_sympd()</a>
to print a warning if the given matrix is not symmetric
</li>
<li>more consistent detection of vector expressions</li>
</ul>
</li>
<br>
<a name="version_9300"></a>
<li>Version 9.300:
<ul>
<li>faster handling of compound complex matrix expressions by <a href="#trace">trace()</a></li>
<li>more efficient handling of element access for inplace modifications in <a href="#SpMat">sparse matrices</a></li>
<li>added <a href="#is_sympd">.is_sympd()</a> to check whether a matrix is symmetric/hermitian positive definite</li>
<li>added <a href="#interp2">interp2()</a> for 2D data interpolation</li>
<li>added <a href="#misc_fns">expm1()</a> and <a href="#misc_fns">log1p()</a></li>
<li>expanded <a href="#is_sorted">.is_sorted()</a> with options <code>"strictascend"</code> and <code>"strictdescend"</code></li>
<li>expanded <a href="#eig_gen">eig_gen()</a> to optionally perform balancing prior to decomposition</li>
</ul>
</li>
<br>
<a name="version_9200"></a>
<li>Version 9.200:
<ul>
<li>faster handling of symmetric positive definite matrices by <a href="#rcond">rcond()</a></li>
<li>faster transpose of matrices with size &geq; 512x512</li>
<li>faster handling of compound sparse matrix expressions by <a href="#accu">accu()</a>, <a href="#diagmat">diagmat()</a>, <a href="#trace">trace()</a></li>
<li>faster handling of sparse matrices by <a href="#join">join_rows()</a></li>
<li>added <a href="#trig_fns">sinc()</a></li>
<li>expanded <a href="#misc_fns">sign()</a> to handle scalar arguments</li>
<li>expanded <a href="#operators">operators</a> (*, %, +, &minus;) to handle sparse matrices with differing element types (eg. multiplication of complex matrix by real matrix)</li>
<li>expanded <a href="#conv_to">conv_to()</a> to allow conversion between sparse matrices with differing element types</li>
<li>expanded <a href="#solve">solve()</a> to optionally allow keeping solutions of systems singular to working precision</li>
</ul>
</li>
<br>
<a name="version_9100"></a>
<li>Version 9.100:
<ul>
<li>faster handling of symmetric/hermitian positive definite matrices by <a href="#solve">solve()</a></li>
<li>faster handling of <a href="#inv_sympd">inv_sympd()</a> in compound expressions</li>
<li>added <a href="#is_symmetric">.is_symmetric()</a></li>
<li>added <a href="#is_hermitian">.is_hermitian()</a></li>
<li>expanded <a href="#spsolve">spsolve()</a> to optionally allow keeping solutions of systems singular to working precision</li>
<li>new <a href="#config_hpp">configuration</a> options <small>ARMA_OPTIMISE_SOLVE_BAND</small> and <small>ARMA_OPTIMISE_SOLVE_SYMPD</small></li>
<li>smarter use of the element cache in sparse matrices</li>
</ul>
</li>
<br>
<a name="version_8600"></a>
<li>Version 8.600:
<ul>
<li>added <a href="#hess">hess()</a> for Hessenberg decomposition</li>
<li>added .row(), .rows(), .col(), .cols() to <a href="#subcube">subcube views</a></li>
<li>expanded <a href="#shed">.shed_rows()</a> and <a href="#shed">.shed_cols()</a> to handle cubes</li>
<li>expanded <a href="#insert">.insert_rows()</a> and <a href="#insert">.insert_cols()</a> to handle cubes</li>
<li>expanded <a href="#subcube">subcube views</a> to allow non-contiguous access to slices</li>
<li>improved tuning of <a href="#SpMat">sparse matrix</a> element access operators</li>
<li>faster handling of tridiagonal matrices by <a href="#solve">solve()</a></li>
<li>faster multiplication of matrices with differing element types when using OpenMP</li>
</ul>
</li>
<br>
<a name="version_8500"></a>
<li>Version 8.500:
<ul>
<li>faster handling of sparse matrices by <a href="#kron">kron()</a> and <a href="#repmat">repmat()</a></li>
<li>faster <a href="#trans">transpose</a> of sparse matrices</li>
<li>faster <a href="#element_access">element access</a> in sparse matrices</li>
<li>faster <a href="#iterators_spmat">row iterators</a> for sparse matrices</li>
<li>faster handling of compound expressions by <a href="#trace">trace()</a></li>
<li>more efficient handling of aliasing in <a href="#submat">submatrix views</a></li>
<li>expanded <a href="#normalise">normalise()</a> to handle sparse matrices</li>
<li>expanded <a href="#transform">.transform()</a> and <a href="#for_each">.for_each()</a> to handle sparse matrices</li>
<li>added <a href="#reverse">reverse()</a> for reversing order of elements</li>
<li>added <a href="#repelem">repelem()</a> for replicating elements</li>
<li>added <a href="#roots">roots()</a> for finding the roots of a polynomial</li>
</ul>
</li>
<br>
<a name="version_8400"></a>
<li>Version 8.400:
<ul>
<li>faster handling of sparse matrices by <a href="#repmat">repmat()</a></li>
<li>faster <a href="#save_load_mat">loading</a> of CSV files</li>
<li>expanded <a href="#kron">kron()</a> to handle sparse matrices</li>
<li>expanded <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a> to handle cubes</li>
<li>expanded <a href="#randi">randi()</a>, <a href="#randu_randn_standalone">randu()</a>, <a href="#randu_randn_standalone">randn()</a>, <a href="#randg">randg()</a> to output single scalars</li>
<li>added <a href="#iterators_submat">submatrix &amp; subcube iterators</a></li>
<li>added <a href="#normcdf">normcdf()</a></li>
<li>added <a href="#mvnrnd">mvnrnd()</a></li>
<li>added <a href="#chi2rnd">chi2rnd()</a></li>
<li>added <a href="#wishrnd">wishrnd()</a> and <a href="#iwishrnd">iwishrnd()</a></li>
</ul>
</li>
<br>
<a name="version_8300"></a>
<li>Version 8.300:
<ul>
<li>faster handling of band matrices by <a href="#solve">solve()</a></li>
<li>faster handling of band matrices by <a href="#chol">chol()</a></li>
<li>faster <a href="#randg">randg()</a> when using OpenMP</li>
<li>added <a href="#normpdf">normpdf()</a></li>
<li>expanded <a href="#save_load_mat">.save()</a> to allow appending new datasets to existing HDF5 files
</ul>
</li>
<br>
<a name="version_8200"></a>
<li>Version 8.200:
<ul>
<li>added <a href="#intersect">intersect()</a> for finding common elements in two vectors/matrices</li>
<li>expanded <a href="#affmul">affmul()</a> to handle non-square matrices</li>
</ul>
</li>
<br>
<a name="version_8100"></a>
<li>Version 8.100:
<ul>
<li>faster incremental construction of <a href="#SpMat">sparse matrices</a> via element access operators</li>
<li>faster <a href="#diag">diagonal views</a> in <a href="#SpMat">sparse matrices</a></li>
<li>expanded <a href="#SpMat">SpMat</a> to save/load sparse matrices in <a href="#save_load_mat">coord format</a></li>
<li>expanded <a href="#save_load_mat">.save()/.load()</a> to allow specification of datasets within HDF5 files</li>
<li>added <a href="#affmul">affmul()</a> to simplify application of affine transformations</li>
<li>warnings and errors are now printed by default to the <i>std::cerr</i> stream</li>
<li>added <a href="#logging">set_cerr_stream()</a> and <a href="#logging">get_cerr_stream()</a> to replace <i>set_stream_err1()</i>, <i>set_stream_err2()</i>, <i>get_stream_err1()</i>, <i>get_stream_err2()</i></li>
<li>new <a href="#config_hpp">configuration</a> options ARMA_COUT_STREAM and ARMA_CERR_STREAM</li>
</ul>
</li>
<br>
<a name="version_7960"></a>
<li>Version 7.960:
<ul>
<li>faster <a href="#randu_randn_standalone">randn()</a> when using OpenMP</li>
<li>faster <a href="#gmm_diag">gmm_diag</a> class, for Gaussian mixture models with diagonal covariance matrices</li>
<li>added <i>.sum_log_p()</i> to the <a href="#gmm_diag">gmm_diag</a> class</li>
<li>added <a href="#gmm_full">gmm_full</a> class, for Gaussian mixture models with full covariance matrices</li>
<li>expanded <a href="#each_slice">.each_slice()</a> to optionally use OpenMP for multi-threaded execution</li>
</ul>
</li>
<br>
<a name="version_7950"></a>
<li>Version 7.950:
<ul>
<li>expanded <a href="#accu">accu()</a> and <a href="#sum">sum()</a> to use OpenMP for processing expressions with computationally expensive element-wise functions</li>
<li>expanded <a href="#trimat">trimatu()</a> and <a href="#trimat">trimatl()</a> to allow specification of the diagonal which delineates the boundary of the triangular part</li>
</ul>
</li>
<br>
<a name="version_7900"></a>
<li>Version 7.900:
<ul>
<li>expanded <a href="#clamp">clamp()</a> to handle cubes</li>
<li>
computationally expensive element-wise functions (such as <a href="#misc_fns">exp()</a>, <a href="#misc_fns">log()</a>, <a href="#trig_fns">cos()</a>, etc)
can now be automatically sped up via <a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP</a>;
this requires a C++11/C++14 compiler with OpenMP 3.1+ support
<ul>
<li>for GCC and clang compilers use the following options to enable both C++11 and OpenMP: <code>-std=c++11 -fopenmp</code></li>
<li><b>Caveat:</b> when using GCC, use of <code>-march=native</code> in conjunction with <code>-fopenmp</code> may lead to speed regressions on recent processors</li>
</ul>
</li>
</ul>
</li>
<br>
<a name="version_7800"></a>
<li>Version 7.800:
<ul>
<li>
changed license to the permissive <a href="https://opensource.org/licenses/Apache-2.0">Apache License 2.0</a>;
see the <a href="http://arma.sourceforge.net/faq.html#license">Questions page</a> for more info
</li>
</ul>
</li>
<br>
<a name="version_7700"></a>
<li>Version 7.700:
<ul>
<li>added <a href="#polyfit">polyfit()</a> and <a href="#polyval">polyval()</a></li>
<li>added second form of <a href="#log_det">log_det()</a> to directly return the result as a complex number</li>
<li>added <a href="#stats_fns">range()</a> to statistics functions</li>
<li>expanded <a href="#trimat">trimatu()/trimatl()</a> and <a href="#symmat">symmatu()/symmatl()</a> to handle sparse matrices</li>
</ul>
</li>
<br>
<a name="version_7600"></a>
<li>Version 7.600:
<ul>
<li>more accurate <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a></li>
<li>expanded <a href="#misc_fns">floor()</a>, <a href="#misc_fns">ceil()</a>, <a href="#misc_fns">round()</a>, <a href="#misc_fns">trunc()</a>, <a href="#misc_fns">sign()</a> to handle sparse matrices</li>
<li>added <a href="#arg">arg()</a>, <a href="#trig_fns">atan2()</a>, <a href="#trig_fns">hypot()</a></li>
</ul>
</li>
<br>
<a name="version_7500"></a>
<li>Version 7.500:
<ul>
<li>expanded <a href="#qz">qz()</a> to optionally specify ordering of the Schur form</li>
<li>expanded <a href="#each_slice">.each_slice()</a> to support matrix multiplication</li>
</ul>
</li>
<br>
<a name="version_7400"></a>
<li>Version 7.400:
<ul>
<li>added <a href="#expmat_sym">expmat_sym()</a>, <a href="#logmat_sympd">logmat_sympd()</a>, <a href="#sqrtmat_sympd">sqrtmat_sympd()</a></li>
<li>added <a href="#replace">.replace()</a></li>
</ul>
</li>
<br>
<a name="version_7300"></a>
<li>Version 7.300:
<ul>
<li>added <a href="#index_min_and_index_max_standalone">index_min()</a> and <a href="#index_min_and_index_max_standalone">index_max()</a> standalone functions</li>
<li>expanded <a href="#submat">.subvec()</a> to accept <a href="#size">size()</a> arguments</li>
<li>more robust handling of non-square matrices by <a href="#lu">lu()</a></li>
</ul>
</li>
<br>
<a name="version_7200"></a>
<li>Version 7.200:
<ul>
<li>added <a href="#index_min_and_index_max_member">.index_min()</a> and <a href="#index_min_and_index_max_member">.index_max()</a> member functions</li>
<li>expanded <a href="#ind2sub">ind2sub()</a> to handle vectors of indices</li>
<li>expanded <a href="#sub2ind">sub2ind()</a> to handle matrix of subscripts</li>
<li>expanded <a href="#expmat">expmat()</a>, <a href="#logmat">logmat()</a> and <a href="#sqrtmat">sqrtmat()</a> to optionally return a bool indicating success</li>
<li>faster handling of compound expressions by <a href="#vectorise">vectorise()</a></li>
</ul>
</li>
<br>
<a name="version_7100"></a>
<li>Version 7.100:
<ul>
<li>added <a href="#misc_fns">erf()</a>, <a href="#misc_fns">erfc()</a>, <a href="#misc_fns">lgamma()</a></li>
<li>added <a href="#subcube">.head_slices()</a> and <a href="#subcube">.tail_slices()</a> to subcube views</li>
<li><a href="#spsolve">spsolve()</a> now requires SuperLU 5.2</li>
<li><a href="#eigs_sym">eigs_sym()</a>, <a href="#eigs_gen">eigs_gen()</a> and <a href="#svds">svds()</a> now use a built-in reimplementation of ARPACK for real (non-complex) matrices; contributed by Yixuan Qiu</li>
</ul>
</li>
<br>
<a name="version_6700"></a>
<li>Version 6.700:
<ul>
<li>added <a href="#trapz">trapz()</a> for numerical integration</li>
<li>added <a href="#logmat">logmat()</a> for calculating the matrix logarithm</li>
<li>added <a href="#regspace">regspace()</a> for generating vectors with regularly spaced elements</li>
<li>added <a href="#logspace">logspace()</a> for generating vectors with logarithmically spaced elements</li>
<li>added <a href="#approx_equal">approx_equal()</a> for determining approximate equality</li>
</ul>
</li>
<br>
<a name="version_6600"></a>
<li>Version 6.600:
<ul>
<li>expanded <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a> to handle cubes</li>
<li>expanded <a href="#Cube">Cube</a> class to handle arbitrarily sized empty cubes (eg. 0x5x2)</li>
<li>added <a href="#shift">shift()</a> for circular shifts of elements</li>
<li>added <a href="#sqrtmat">sqrtmat()</a> for finding the square root of a matrix</li>
</ul>
</li>
<br>
<a name="version_6500"></a>
<li>Version 6.500:
<ul>
<li>added <a href="#conv2">conv2()</a> for 2D convolution</li>
<li>added stand-alone <a href="#kmeans">kmeans()</a> function for clustering data</li>
<li>added <a href="#misc_fns">trunc()</a></li>
<li>extended <a href="#conv">conv()</a> to optionally provide central convolution</li>
<li>faster handling of multiply-and-accumulate by <a href="#accu">accu()</a> when using Intel MKL, ATLAS or OpenBLAS</li>
</ul>
</li>
<br>
<a name="version_6400"></a>
<li>Version 6.400:
<ul>
<li>expanded <a href="#each_colrow">each_col()</a>, <a href="#each_colrow">each_row()</a> and <a href="#each_slice">each_slice()</a> to handle C++11 lambda functions</li>
<li>added <a href="#ind2sub">ind2sub()</a> and <a href="#sub2ind">sub2ind()</a></li>
</ul>
</li>
<br>
<a name="version_6300"></a>
<li>Version 6.300:
<ul>
<li>expanded <a href="#solve">solve()</a> to find approximate solutions for rank-deficient systems</li>
<li>faster handling of <a href="#submat">non-contiguous submatrix views</a> in compound expressions</li>
<li>added <a href="#for_each">.for_each()</a> to <i>Mat</i>, <i>Row</i>, <i>Col</i>, <i>Cube</i> and <i>field</i> classes</li>
<li>added <a href="#rcond">rcond()</a> for estimating the reciprocal condition number</li>
</ul>
</li>
<br>
<a name="version_6200"></a>
<li>Version 6.200:
<ul>
<li>expanded <a href="#diagmat">diagmat()</a> to handle non-square matrices and arbitrary diagonals</li>
<li>expanded <a href="#trace">trace()</a> to handle non-square matrices</li>
</ul>
</li>
<br>
<a name="version_6100"></a>
<li>Version 6.100:
<ul>
<li>faster <a href="#norm">norm()</a> and <a href="#normalise">normalise()</a> when using Intel MKL, ATLAS or OpenBLAS</li>
<li>added Schur decomposition: <a href="#schur">schur()</a></li>
<li>stricter handling of matrix objects by <a href="#hist">hist()</a> and <a href="#histc">histc()</a></li>
<li><a href="#adv_constructors_mat">advanced constructors</a> for using auxiliary memory by Mat, Col, Row and Cube now have the default of <i>strict = false</i></li>
<li><a href="#Cube">Cube</a> class now delays allocation of <a href="#subcube">.slice()</a> related structures until needed</li>
<li>expanded <a href="#join_slices">join_slices()</a> to handle joining cubes with matrices</li>
</ul>
</li>
<br>
<a name="version_5600"></a>
<li>Version 5.600:
<ul>
<li>added <a href="#each_slice">.each_slice()</a> for repeated matrix operations on each slice of a cube</li>
<li>expanded <a href="#each_colrow">.each_col()</a> and <a href="#each_colrow">.each_row()</a> to handle out-of-place operations</li>
</ul>
</li>
<br>
<a name="version_5500"></a>
<li>Version 5.500:
<ul>
<li>expanded object constructors and generators to handle <a href="#size">size()</a> based specification of dimensions</li>
</ul>
</li>
<br>
<a name="version_5400"></a>
<li>Version 5.400:
<ul>
<li>added <a href="#find_unique">find_unique()</a> for finding indices of unique values</li>
<li>added <a href="#diff">diff()</a> for calculating differences between consecutive elements</li>
<li>added <a href="#cumprod">cumprod()</a> for calculating cumulative product</li>
<li>added <a href="#null">null()</a> for finding the orthonormal basis of null space</li>
<li>expanded <a href="#interp1">interp1()</a> to handle repeated locations</li>
<li>expanded <a href="#unique">unique()</a> to handle complex numbers</li>
<li>faster <a href="#flip">flipud()</a></li>
<li>faster row-wise <a href="#cumsum">cumsum()</a></li>
</ul>
</li>
<br>
<a name="version_5300"></a>
<li>Version 5.300:
<ul>
<li>added generalised Schur decomposition: <a href="#qz">qz()</a></li>
<li>added <a href="#has_inf">.has_inf()</a> and <a href="#has_nan">.has_nan()</a></li>
<li>expanded <a href="#interp1">interp1()</a> to handle out-of-domain locations</li>
<li>expanded <a href="#SpMat">sparse matrix</a> class with <a href="#set_imag">.set_imag()</a> and <a href="#set_imag">.set_real()</a></li>
<li>expanded <a href="#imag_real">imag()</a>, <a href="#imag_real">real()</a> and <a href="#conj">conj()</a> to handle sparse matrices</li>
<li>expanded <a href="#diagmat">diagmat()</a>, <a href="#reshape">reshape()</a> and <a href="#resize">resize()</a> to handle sparse matrices</li>
<li>faster sparse <a href="#sum">sum()</a></li>
<li>faster row-wise <a href="#sum">sum()</a>, <a href="#stats_fns">mean()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a></li>
<li>updated <a href="#constants">physical constants</a> to NIST 2014 CODATA values</li>
</ul>
</li>
<br>
<a name="version_5200"></a>
<li>Version 5.200:
<ul>
<li>added <a href="#orth">orth()</a> for finding the orthonormal basis of the range space of a matrix</li>
<li>expanded <a href="#element_initialisation">element initialisation</a> to handle nested initialiser lists (C++11)</li>
</ul>
</li>
<br>
<a name="version_5100"></a>
<li>Version 5.100:
<ul>
<li>added <a href="#interp1">interp1()</a> for 1D interpolation</li>
<li>added <a href="#is_sorted">.is_sorted()</a> for checking whether a vector or matrix has sorted elements</li>
<li>updated <a href="#constants">physical constants</a> to NIST 2010 CODATA values</li>
</ul>
</li>
<br>
<a name="version_5000"></a>
<li>Version 5.000:
<ul>
<li>added <a href="#spsolve">spsolve()</a> for solving sparse systems of linear equations</li>
<li>added <a href="#svds">svds()</a> for singular value decomposition of sparse matrices</li>
<li>added <a href="#nonzeros">nonzeros()</a> for extracting non-zero values from matrices</li>
<li>added handling of <a href="#diag">diagonal views</a> by sparse matrices
<li>expanded <a href="#repmat">repmat()</a> to handle sparse matrices
<li>expanded <a href="#join">join_rows()</a> and <a href="#join">join_cols()</a> to handle sparse matrices
<li><a href="#sort_index">sort_index()</a> and <a href="#sort_index">stable_sort_index()</a> have been placed in the delayed operations framework for increased efficiency
<li>use of <a href="#uword">64 bit integers</a> is automatically enabled when using a C++11 compiler</li>
</ul>
</li>
<br>
<a name="version_4650"></a>
<li>Version 4.650:
<ul>
<li>added <a href="#randg">randg()</a> for generating random values from gamma distributions (C++11 only)</li>
<li>added <i>.head_rows()</i> and <i>.tail_rows()</i> to <a href="#submat">submatrix views</a></li>
<li>added <i>.head_cols()</i> and <i>.tail_cols()</i> to <a href="#submat">submatrix views</a></li>
<li>expanded <a href="#eigs_sym">eigs_sym()</a> to optionally calculate eigenvalues with smallest/largest algebraic values</li>
</ul>
</li>
<br>
<a name="version_4600"></a>
<li>Version 4.600:
<ul>
<li>added <i>.head()</i> and <i>.tail()</i> to <a href="#submat">submatrix views</a></li>
<li>faster matrix transposes within compound expressions</li>
<li>faster in-place matrix multiplication</li>
<li>faster <a href="#accu">accu()</a> and <a href="#norm">norm()</a> when compiling with <i>-O3 -ffast-math -march=native</i> (gcc and clang)
</ul>
</li>
<br>
<a name="version_4550"></a>
<li>Version 4.550:
<ul>
<li>added matrix exponential function: <a href="#expmat">expmat()</a></li>
<li>faster <i>.log_p()</i> and <i>.avg_log_p()</i> functions in the <a href="#gmm_diag">gmm_diag</a> class when compiling with OpenMP enabled</li>
<li>faster handling of in-place addition/subtraction of expressions with an outer product
</ul>
</li>
<br>
<a name="version_4500"></a>
<li>Version 4.500:
<ul>
<li>faster handling of complex vectors by <a href="#norm">norm()</a></li>
<li>expanded <a href="#chol">chol()</a> to optionally specify output matrix as upper or lower triangular</li>
<li>better handling of non-finite values when <a href="#save_load_mat">saving</a> matrices as text files</li>
</ul>
</li>
<br>
<a name="version_4450"></a>
<li>Version 4.450:
<ul>
<li>faster handling of matrix transposes within compound expressions</li>
<li>expanded <a href="#symmat">symmatu()/symmatl()</a> to optionally disable taking the complex conjugate of elements</li>
<li>expanded <a href="#sort_index">sort_index()</a> to handle complex vectors</li>
<li>expanded the <a href="#gmm_diag">gmm_diag</a> class with functions to generate random samples</li>
</ul>
</li>
<br>
<a name="version_4400"></a>
<li>Version 4.400:
<ul>
<li>faster handling of subvectors by <a href="#dot">dot()</a></li>
<li>faster handling of aliasing by <a href="#submat">submatrix</a> views</li>
<li>added <a href="#clamp">clamp()</a> for clamping values to be between lower and upper limits</li>
<li>added <a href="#gmm_diag">gmm_diag</a> class for statistical modelling of data using Gaussian Mixture Models</li>
<li>expanded <a href="#batch_constructors_sp_mat">batch insertion constructors</a> for sparse matrices to add values at repeated locations</li>
</ul>
</li>
<br>
<a name="version_4320"></a>
<li>Version 4.320:
<ul>
<li>expanded <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> to use an optional tolerance parameter</li>
<li>expanded <a href="#eig_sym">eig_sym()</a> to automatically fall back to standard decomposition method if divide-and-conquer fails</li>
<li>cmake-based installer enables use of C++11 random number generator when using gcc 4.8.3+ in C++11 mode</li>
</ul>
</li>
<br>
<a name="version_4300"></a>
<li>Version 4.300:
<ul>
<li>added <a href="#find_finite">find_finite()</a> and <a href="#find_nonfinite">find_nonfinite()</a></li>
<li>expressions <i>X=<a href="#inv">inv</a>(A)*B*C</i> and <i>X=A<a href="#i_member">.i()</a>*B*C</i> are automatically converted to <i>X=<a href="#solve">solve</a>(A,B*C)</i></li>
</ul>
</li>
<br>
<a name="version_4200"></a>
<li>Version 4.200:
<ul>
<li>faster transpose of sparse matrices</li>
<li>more efficient handling of aliasing during matrix multiplication</li>
<li>faster <a href="#inv">inverse</a> of matrices marked as diagonal</li>
</ul>
</li>
<br>
<a name="version_4100"></a>
<li>Version 4.100:
<ul>
<li>added <a href="#normalise">normalise()</a> for normalising vectors to unit <i>p</i>-norm</li>
<li>extended the <a href="#field">field class</a> to handle 3D layout</li>
<li>extended <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a> to obtain eigenvalues of various forms (eg. largest or smallest magnitude)</li>
<li>automatic SIMD vectorisation of elementary expressions (eg. matrix addition) when using Clang 3.4+ with -O3 optimisation</li>
<li>faster handling of sparse submatrix views</li>
</ul>
</li>
<br>
<a name="version_4000"></a>
<li>Version 4.000:
<ul>
<li>added eigen decompositions of sparse matrices: <a href="#eigs_sym">eigs_sym()</a> and <a href="#eigs_gen">eigs_gen()</a></li>
<li>added eigen decomposition for pair of matrices: <a href="#eig_pair">eig_pair()</a></li>
<li>added simpler forms of <a href="#eig_gen">eig_gen()</a></li>
<li>added condition number of matrices: <a href="#cond">cond()</a></li>
<li>expanded <a href="#find">find()</a> to handle cubes</li>
<li>expanded <a href="#subcube">subcube views</a> to access elements specified in a vector</li>
<li>template argument for <a href="#running_stat_vec">running_stat_vec</a> expanded to accept vector types</li>
<li>more robust fast <a href="#inv">inverse</a> of 4x4 matrices</li>
<li>faster divide-and-conquer decompositions are now used by default for
<a href="#eig_sym">eig_sym()</a>,
<a href="#pinv">pinv()</a>,
<a href="#princomp">princomp()</a>,
<a href="#rank">rank()</a>,
<a href="#svd">svd()</a>,
<a href="#svd_econ">svd_econ()</a>
</li>
<li>
the form <i>inv(sympd(X))</i> no longer assumes that <i>X</i> is positive definite; use <a href="#inv_sympd">inv_sympd()</a> instead 
</li>
</ul>
</li>
<br>
<a name="version_3930"></a>
<li>Version 3.930:
<ul>
<li>added <a href="#size">size()</a> based specifications of <a href="#submat">submatrix view</a> sizes</li>
<li>added element-wise variants of <a href="#min_and_max">min()</a> and <a href="#min_and_max">max()</a></li>
<li>added divide-and-conquer variant of <a href="#svd_econ">svd_econ()</a></li>
<li>added divide-and-conquer variant of <a href="#pinv">pinv()</a></li>
<li>added <a href="#randi">randi()</a> for generating matrices with random integer values</li>
<li>added <a href="#inplace_trans">inplace_trans()</a> for memory efficient in-place transposes</li>
<li>added more intuitive specification of sort direction in <a href="#sort">sort()</a> and <a href="#sort_index">sort_index()</a></li>
<li>added more intuitive specification of method in <a href="#det">det()</a>, <a href="#i_member">.i()</a>, <a href="#inv">inv()</a> and <a href="#solve">solve()</a></li>
<li>more precise timer for the <a href="#wall_clock">wall_clock</a> class when using C++11</li>
</ul>
</li>
<br>
<a name="version_3920"></a>
<li>Version 3.920:
<ul>
<li>faster <a href="#zeros_member">.zeros()</a></li>
<li>faster <a href="#misc_fns">round()</a>, <a href="#misc_fns">exp2()</a> and <a href="#misc_fns">log2()</a> when using C++11</li>
<li>added signum function: <a href="#misc_fns">sign()</a></li>
<li>added move constructors when using C++11</li>
<li>added 2D fast Fourier transform: <a href="#fft2">fft2()</a></li>
<li>added <a href="#subcube">.tube()</a> for easier extraction of vectors and subcubes from cubes</li>
<li>added specification of a fill type during construction of <a href="#Mat">Mat</a>, <a href="#Col">Col</a>, <a href="#Row">Row</a> and <a href="#Cube">Cube</a> classes,
eg. <i>mat&nbsp;X(4,&nbsp;5,&nbsp;fill::zeros)</i></li>
</ul>
</li>
<br>
<a name="version_3910"></a>
<li>Version 3.910:
<ul>
<li>faster multiplication of a matrix with a transpose of itself, ie. <i>X*X.t()</i> and <i>X.t()*X</i></li>
<li>added <a href="#vectorise">vectorise()</a> for reshaping matrices into vectors</li>
<li>added <a href="#all">all()</a> and <a href="#any">any()</a> for indicating presence of elements satisfying a relational condition</li>
</ul>
</li>
<br>
<a name="version_3900"></a>
<li>Version 3.900:
<ul>
<li>added automatic SSE2 vectorisation of elementary expressions (eg. matrix addition) when using GCC 4.7+ with -O3 optimisation</li>
<li>faster <a href="#stats_fns">median()</a></li>
<li>faster handling of compound expressions with transposes of <a href="#submat">submatrix</a> rows</li>
<li>faster handling of compound expressions with transposes of complex vectors</li>
<li>added support for <a href="#save_load_mat">saving &amp; loading</a> of <a href="#Cube">cubes</a> in HDF5 format</li>
</ul>
</li>
<br>
<a name="version_3820"></a>
<li>Version 3.820:
<ul>
<li>faster <a href="#as_scalar">as_scalar()</a> for compound expressions</li>
<li>faster transpose of small vectors</li>
<li>faster matrix-vector product for small vectors</li>
<li>faster multiplication of small <a href="#adv_constructors_mat_fixed">fixed size matrices</a></li>
</ul>
</li>
<br>
<a name="version_3810"></a>
<li>Version 3.810:
<ul>
<li>added fast Fourier transform: <a href="#fft">fft()</a></li>
<li>added handling of <a href="#imbue">.imbue()</a> and <a href="#transform">.transform()</a> by submatrices and subcubes</li>
<li>added <a href="#batch_constructors_sp_mat">batch insertion constructors</a> for sparse matrices
</ul>
</li>
<br>
<a name="version_3800"></a>
<li>Version 3.800:
<ul>
<li>added <a href="#imbue">.imbue()</a> for filling a matrix/cube with values provided by a functor or lambda expression</li>
<li>added <a href="#swap">.swap()</a> for swapping contents with another matrix</li>
<li>added <a href="#transform">.transform()</a> for transforming a matrix/cube using a functor or lambda expression</li>
<li>added <a href="#misc_fns">round()</a> for rounding matrix elements towards nearest integer</li>
<li>faster <a href="#find">find()</a></li>
<li>changed license to the <a href="http://www.mozilla.org/MPL/2.0/">Mozilla Public License 2.0</a></li>
</ul>
<br>
</li>
<a name="version_36"></a>
<li>Version 3.6:
<ul>
<li>faster handling of compound expressions with submatrices and subcubes</li>
<li>faster <a href="#trace">trace()</a></li>
<li>added support for loading matrices as text files with <i>NaN</i> and <i>Inf</i> elements</li>
<li>added <a href="#sort_index">stable_sort_index()</a>, which preserves the relative order of elements with equivalent values</li>
<li>added handling of <a href="#SpMat">sparse matrices</a> by <a href="#stats_fns">mean()</a>, <a href="#stats_fns">var()</a>, <a href="#norm">norm()</a>, <a href="#abs">abs()</a>, <a href="#misc_fns">square()</a>, <a href="#misc_fns">sqrt()</a></li>
<li>added saving and loading of sparse matrices in <i>arma_binary</i> format</li>
</ul>
<br>
</li>
<a name="version_34"></a>
<li>Version 3.4:
<ul>
<li>added economical QR decomposition: <a href="#qr_econ">qr_econ()</a></li>
<li>added <a href="#each_colrow">.each_col() &amp; .each_row()</a> for vector operations repeated on each column or row of a matrix</li>
<li>added preliminary support for <a href="#SpMat">sparse matrices</a></li>
<li>added ability to <a href="#save_load_mat">save and load</a> matrices in HDF5 format</li>
<li>faster <a href="#svd">singular value decomposition</a> via optional use of divide-and-conquer algorithm</li>
<li>faster <a href="#randu_randn_member">.randn()</a></li>
<li>faster <a href="#dot">dot() and cdot()</a> for complex numbers</li>
</ul>
<br>
</li>
<a name="version_32"></a>
<li>Version 3.2:
<ul>
<li>added <a href="#unique">unique()</a>, for finding unique elements of a matrix</li>
<li>added <a href="#eval_member">.eval()</a>, for forcing the evaluation of delayed expressions</li>
<li>faster <a href="#eig_sym">eigen decomposition</a> via optional use of divide-and-conquer algorithm</li>
<li>faster <a href="#t_st_members">transpose</a> of vectors and compound expressions</li>
<li>faster handling of <a href="#diag">diagonal views</a></li>
<li>faster handling of tiny <a href="#adv_constructors_col_fixed">fixed size</a> vectors (&le; 4 elements)</li>
</ul>
<br>
</li>
<a name="version_30"></a>
<li>Version 3.0:
<ul>
<li>added shorthand for inverse: <a href="#i_member">.i()</a></li>
<li>added <a href="#constants">datum</a> class</li>
<li>added <a href="#hist">hist()</a> and <a href="#histc">histc()</a></li>
<li>added non-contiguous <a href="#submat">submatrix views</a></li>
<li>faster handling of <a href="#submat">submatrix views</a> with a single row or column</li>
<li>faster element access in <a href="#adv_constructors_mat_fixed">fixed size matrices</a></li>
<li>faster <a href="#repmat">repmat()</a></li>
<li>expressions <i>X=<a href="#inv">inv</a>(A)*B</i> and <i>X=A<a href="#i_member">.i()</a>*B</i> are automatically converted to <i>X=<a href="#solve">solve</a>(A,B)</i>
<li>better detection of vector expressions by <a href="#sum">sum()</a>, <a href="#cumsum">cumsum()</a>, <a href="#prod">prod()</a>, <a href="#min_and_max">min()</a>, <a href="#min_and_max">max()</a>, <a href="#stats_fns">mean()</a>, <a href="#stats_fns">median()</a>, <a href="#stats_fns">stddev()</a>, <a href="#stats_fns">var()</a>
<li>faster generation of random numbers
(eg. <a href="#randu_randn_standalone">randu()</a> and <a href="#randu_randn_standalone">randn()</a>),
via an algorithm that produces slightly different numbers than in 2.x
</li>
<li>
support for tying writable auxiliary (external) memory to fixed size matrices has been removed;
instead, you can use standard matrices with <a href="#adv_constructors_mat">writable auxiliary memory</a>,
or initialise fixed size matrices by <a href="#adv_constructors_mat">copying the memory</a>;
using auxiliary memory with standard matrices is unaffected
</li>
<li>
<i>.print_trans()</i> and <i>.raw_print_trans()</i> have been removed;
instead, you can chain <i><a href="#t_st_members">.t()</a></i> and <i><a href="#print">.print()</a></i> to achieve a similar result: <i>X.t().print()</i>
</li>
</ul>
<br>
</li>
<a name="version_24"></a>
<li>Version 2.4:
<ul>
<li>added shorter forms of transposes: <a href="#t_st_members">.t()</a> and <a href="#t_st_members">.st()</a></li>
<li>added <a href="#resize_member">.resize()</a> and <a href="#resize">resize()</a></li>
<li>added optional use of 64 bit indices (allowing matrices to have more than 4 billion elements), enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i></li>
<li>added experimental support for C++11 initialiser lists, enabled via ARMA_USE_CXX11 in <i>include/armadillo_bits/config.hpp</i></li>
<li>refactored code to eliminate warnings when using the Clang C++ compiler</li>
<li><a href="#Mat">umat</a>, <a href="#Col">uvec</a>, <a href="#min_and_max_member">.min()</a> and <a href="#min_and_max_member">.max()</a>
have been changed to use the <a href="#uword"><i>uword</i></a> type instead of the <i>u32</i> type;
by default the <i>uword</i> and <i>u32</i> types are equivalent (ie. unsigned integer type with a minimum width 32 bits);
however, when the use of 64 bit indices is enabled via ARMA_64BIT_WORD in <i>include/armadillo_bits/config.hpp</i>,
the <i>uword</i> type then has a minimum width of 64 bits
</ul>
</li>
<br>
<li>Version 2.2:
<ul>
<li>added <a href="#svd_econ">svd_econ()</a></li>
<li>added <a href="#toeplitz">circ_toeplitz()</a></li>
<li>added <a href="#is_vec">.is_colvec()</a> and <a href="#is_vec">.is_rowvec()</a></li>
</ul>
<br>
<li>Version 2.0:
<ul>
<li><a href="#det">det()</a>, <a href="#inv">inv()</a> and <a href="#solve">solve()</a> can be forced to use more precise algorithms for tiny matrices (&le;&nbsp;4x4)</li>
<li>added <a href="#syl">syl()</a>, for solving Sylvester's equation</li>
<li>added <a href="#trans">strans()</a>, for transposing a complex matrix without taking the complex conjugate</li>
<li>added <a href="#symmat">symmatu()</a> and <a href="#symmat">symmatl()</a></li>
<li>added submatrices of <a href="#submat">submatrices</a></li>
<li>faster <a href="#inv">inverse</a> of symmetric positive definite matrices</li>
<li>faster element access for <a href="#adv_constructors_mat_fixed">fixed size</a> matrices</li>
<li>faster multiplication of tiny matrices (eg. 4x4)</li>
<li>faster compound expressions containing <a href="#submat">submatrices</a></li>
<li>added handling of arbitrarily sized empty matrices (eg. 5x0)</li>
<li>added .count() member function in <a href="#running_stat">running_stat</a> and <a href="#running_stat_vec">running_stat_vec</a></li>
<li>added <a href="#save_load_mat">loading &amp; saving</a> of matrices as CSV text files</li>
<li><a href="#trans">trans()</a> now takes the complex conjugate when transposing a complex matrix</li>
<li>forms of
<a href="#chol">chol()</a>, <a href="#eig_sym">eig_sym()</a>, <a href="#eig_gen">eig_gen()</a>,
<a href="#inv">inv()</a>, <a href="#lu">lu()</a>, <a href="#pinv">pinv()</a>, <a href="#princomp">princomp()</a>,
<a href="#qr">qr()</a>, <a href="#solve">solve()</a>, <a href="#svd">svd()</a>, <a href="#syl">syl()</a>
that do not return a bool indicating success now throw <i>std::runtime_error</i> exceptions when failures are detected</li>
<li>princomp_cov() has been removed; <a href="#eig_sym">eig_sym()</a> in conjunction with <a href="#cov">cov()</a> can be used instead</li>
<li><a href="#is_vec">.is_vec()</a> now outputs <i>true</i> for empty vectors (eg. 0x1)</li>
<li>set_log_stream() &amp; get_log_stream() have been replaced by <a href="#logging">set_stream_err1()</a> &amp; <a href="#logging">get_stream_err1()</a></li>
</ul>
<br>
<li>Version 1.2:
<ul>
<li>added <a href="#min_and_max_member">.min() &amp; .max()</a> member functions of Mat and Cube</li>
<li>added <a href="#misc_fns">floor()</a> and <a href="#misc_fns">ceil()</a></li>
<li>added representation of &ldquo;not a number&rdquo;: math::nan()</li>
<li>added representation of infinity: math::inf()</li>
<li><a href="#in_range">.in_range()</a> expanded to use <b>span()</b> arguments</li>
<li><a href="#adv_constructors_mat">fixed size</a> matrices and vectors can use auxiliary (external) memory</li>
<li><a href="#submat">submatrices</a> and <a href="#subfield">subfields</a> can be accessed via <i><b>X(</b>&nbsp;<b>span(</b>a,b<b>)</b>,&nbsp;<b>span(</b>c,d<b>)</b>&nbsp;<b>)</b></i></li>
<li><a href="#subcube">subcubes</a> can be accessed via <i><b>X(</b>&nbsp;<b>span(</b>a,b<b>)</b>,&nbsp;<b>span(</b>c,d<b>)</b>,&nbsp;<b>span(</b>e,f<b>)</b>&nbsp;<b>)</b></i></li>
<li>the two argument version of <i><b>span</b></i> can be replaced by
<i><b>span::all</b></i> or <i><b>span()</b></i>, to indicate an entire range
</li>
<li>for cubes, the two argument version of <i><b>span</b></i> can be replaced by
a single argument version, <i><b>span(</b>a<b>)</b></i>, to indicate a single column, row or slice
</li>
<li>arbitrary "flat" subcubes can be interpreted as matrices; for example:
<ul>
<pre>
cube Q = randu&lt;cube&gt;(5,3,4);
mat  A = Q(&nbsp;span(1),&nbsp;span(1,2),&nbsp;span::all&nbsp;);
// A has a size of 2x4

vec v = ones&lt;vec&gt;(4);
Q(&nbsp;span(1),&nbsp;span(1),&nbsp;span::all&nbsp;)&nbsp;=&nbsp;v;
</pre>
</ul>
</li>
<li>added interpretation of matrices as triangular through <a href="#trimat">trimatu() / trimatl()</a></li>
<li>added explicit handling of triangular matrices by <a href="#solve">solve()</a> and <a href="#inv">inv()</a></li>
<li>extended syntax for <a href="#submat">submatrices</a>, including access to elements whose indices are specified in a vector</li>
<li>added ability to change the stream used for <a href="#logging">logging</a> of errors and warnings</li>
<li>added ability to <a href="#save_load_mat">save/load matrices</a> in raw binary format</li>
<li>added cumulative sum function: <a href="#cumsum">cumsum()</a></li>
</ul>
</li>
<br>
<li>
Changed in 1.0 (compared to earlier 0.x development versions):
<ul>
<li>
the 3 argument version of <a href="#lu">lu()</a>,
eg. lu(L,U,X),
provides L and U which should be the same as produced by Octave 3.2
(this was not the case in versions prior to 0.9.90)
</li>
<br>
<li>
rand() has been replaced by <a href="#randu_randn_standalone">randu()</a>;
this has been done to avoid confusion with <a href="http://cplusplus.com/reference/clibrary/cstdlib/rand/">std::rand()</a>,
which generates random numbers in a different interval
</li>
<br>
<li>
In versions earlier than 0.9.0,
some multiplication operations directly converted result matrices with a size of 1x1 into scalars.
This is no longer the case.
If you know the result of an expression will be a 1x1 matrix and wish to treat it as a pure scalar,
use the <a href="#as_scalar">as_scalar()</a> wrapping function
</li>
<br>
<li>
Almost all functions have been placed in the delayed operations framework (for speed purposes).
This may affect code which assumed that the output of some functions was a pure matrix.
The solution is easy, as explained below.
<br>
<br>
In general, Armadillo queues operations before executing them.
As such, the direct output of an operation or function cannot be assumed to be a directly accessible matrix.
The queued operations are executed when the output needs to be stored in a matrix,
eg. <i>mat&nbsp;B&nbsp;=&nbsp;trans(A)</i> or <i>mat&nbsp;B(trans(A))</i>.
If you need to force the execution of the delayed operations,
place the operation or function inside the corresponding Mat constructor.
For example, if your code assumed that the output of some functions was a pure matrix,
eg. <i>chol(m).diag()</i>, change the code to <i>mat(chol(m)).diag()</i>.
Similarly, if you need to pass the result of an operation such as <i>A+B</i> to one of your own functions,
use <i>my_function(&nbsp;mat(A+B)&nbsp;)</i>.
</li>
</ul>
</li>
</ul>
</li>
<br>
</ul>

<!-- END CONTENT -->


<hr>
<br>
<br>

</td>
</tr>
</tbody>
</table>
</center>
</body>
</html>
